Update doc (#9)

* restructure docs

* update doc

* update requirements, make output optional arg

* fix formatting

.flake8

@@ -1,3 +1,4 @@
 [flake8]
+ignore = E501
 exclude = .git,__pycache__,.ipynb_checkpoints
 max-line-length = 90

.github/workflows/main.yml

@@ -35,5 +35,5 @@ jobs:
         pip install -r requirements.txt
     - name: Run pytest
       run: |
-        cd src
+        cd src/mypackage
         python -m pytest

.pre-commit-config.yaml

@@ -1,23 +1,11 @@
 
 repos:
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.5.0
+    rev: 0.6.0
     hooks:
       - id: nbstripout
         files: ".ipynb"
   - repo: https://github.com/psf/black
     rev: 22.6.0
     hooks:
-    - id: black
-  - repo: https://github.com/dfm/black_nbconvert
-    rev: v0.4.0
-    hooks:
-      - id: black_nbconvert
-  -   repo: https://github.com/pycqa/flake8
-      rev: 4.0.1 
-      hooks:
-      -   id: flake8
-  -   repo: https://github.com/s-weigand/flake8-nb
-      rev: v0.4.0 
-      hooks:
-      -   id: flake8-nb
+    - id: black

README.md

@@ -10,7 +10,7 @@
     1. [License, bug tracker, references, citations](doc/further.md)
     1. [Source code description](doc/sphinxdoc.md) - functions and classes, modules, variables
 
-# python-project-template
+## python-project-template
 
 This is a template for your software project. The example code calculates the side length of a square or a pentagon, that contains the same area as a circle of given radius r.
 
@@ -24,7 +24,7 @@ The documentation requires `sphinx` to be installed on your system.
 For installation, run  
 `source setup.sh`
 
-This will pip-install sphinx on your system.
+This will pip-install the requirements of the template (`numpy`, `sphinx` and extensions, and `pytest`) on your system.
 
 If you want to run the test module manually, execute  
 `python -m pytest`  

doc/source/conf.py

@@ -12,28 +12,29 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../../src/'))
+
+sys.path.insert(0, os.path.abspath("../../src/mypackage"))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'python-project-template'
-copyright = '2020, Scientific Software Center'
-author = 'Scientific Software Center'
+project = "python-project-template"
+copyright = "2020, Scientific Software Center"
+author = "Scientific Software Center"
 
 # The full version, including alpha/beta/rc tags
-release = '0.1'
+release = "0.1"
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ["sphinx.ext.autodoc", "myst_parser", "sphinx.ext.napoleon"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -46,9 +47,9 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = "alabaster"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]

doc/source/index.rst

@@ -10,10 +10,9 @@ Welcome to python-project-template's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   readme_link
    modules
-   main
-   transform
-   test_transform
+   license_link
 
 Indices and tables
 ==================

doc/source/license_link.md

@@ -0,0 +1,4 @@
+# License information
+
+```{include} ../../LICENSE
+```

doc/source/modules.rst

@@ -1,5 +1,5 @@
-src
-===
+mypackage
+=========
 
 .. toctree::
    :maxdepth: 4

doc/source/readme_link.md

@@ -0,0 +1,3 @@
+# Readme
+```{include} ../../README.md
+```

requirements.txt

@@ -1,3 +1,9 @@
 numpy==1.23.1
+click==7.1.2
 sphinx==5.1.1
+myst-parser==0.18.0
+sphinxcontrib-napoleon==0.7
 pytest==7.1.2
+black==20.8b0
+nbstripout==0.6.0
+flake8==4.0.1

src/main.py → src/mypackage/main.py

@@ -7,33 +7,51 @@
 
 def parse_command_line():
     """Function to parse user input. User input is a float and a string.
-    :Returns: radius of the circle (float) and which type of object is
-    selected (string)."""
-    parser = argparse.ArgumentParser(description="""Program to calculate side
+
+    :Returns: radius of the circle (float) and which type of object is selected (string)."""
+    parser = argparse.ArgumentParser(
+        description="""Program to calculate side
         length of square (pentagon) containing the same area as circle with
         given radius. Provide input values. Check -h or --help for options.
-        Usage: ./main.py square -r 4""")
-    parser.add_argument("-r", "--radius", default=3.0, help="Radius of the \
+        Usage: ./main.py square -r 4"""
+    )
+    parser.add_argument(
+        "-r",
+        "--radius",
+        default=3.0,
+        help="Radius of the \
         circle, in cm. \
-        Default value: 3.0 cm")
-    parser.add_argument("output", choices=["square", "pentagon"],
-                        help="Choice of output object.")
+        Default value: 3.0 cm",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="square",
+        choices=["square", "pentagon"],
+        help="Choice of output object.",
+    )
 
     args = parser.parse_args()
 
     r = float(args.radius)
     l_output = args.output
     if l_output == "square":
-        print("""Calculation of the side length of a square containing the
-        same area as a selected circle.""")
+        print(
+            """Calculation of the side length of a square containing the
+        same area as a selected circle."""
+        )
         calc_square = True
     elif l_output == "pentagon":
-        print("""Calculation of the side length of a pentagon containing the
-            same area as a selected circle.""")
+        print(
+            """Calculation of the side length of a pentagon containing the
+            same area as a selected circle."""
+        )
         calc_square = False
     else:
-        sys.exit("No further output objects have been implemented \
-            yet! Aborting...")
+        sys.exit(
+            "No further output objects have been implemented \
+            yet! Aborting..."
+        )
 
     return r, calc_square
 

src/test_transform.py → src/mypackage/test_transform.py

@@ -5,23 +5,25 @@
 import transform as tf
 import pytest
 
-@pytest.mark.parametrize("myinput, myref",
-                         [(1, np.pi),
-                          (0, 0),
-                          (2.1, np.pi * 2.1**2)]
-                        )
+
+@pytest.mark.parametrize(
+    "myinput, myref", [(1, np.pi), (0, 0), (2.1, np.pi * 2.1**2)]
+)
 def test_area_circ(myinput, myref):
     assert tf.area_circ(myinput) == myref
 
+
 def test_area_circ_values():
     """Make sure value errors are recognized for area_circ."""
     with pytest.raises(ValueError):
         tf.area_circ(-5)
 
+
 def test_side_square():
     """Test the computed side values for the square against a reference."""
     assert tf.side_square(np.pi) == np.sqrt(np.pi)
 
+
 def test_side_pentagon():
     """Test the computed side values for the pentagon against a reference."""
     assert tf.side_pentagon(np.pi) == pytest.approx(1.35129587)