Autodoc to use type hinting (#152)

Author: bblay

.github/workflows/build_docs.yml

@@ -19,12 +19,12 @@ jobs:
     - name: install sphinx
       run: pip install sphinx sphinx-rtd-theme
     - name: install fab
-      run: pip install .
+      run: pip install .[docs]
     - name: build docs
       run: |
         cd docs
         rm -rf build
-        sphinx-apidoc -f -o source/apidoc ../source/fab
+        sphinx-apidoc --separate --module-first -d 3 -f -o source/apidoc ../source/fab
         make html
     - name: move built docs to docs root
       run: |

.gitignore

@@ -105,3 +105,6 @@ venv.bak/
 
 # Profiler stats
 .pstats
+
+# apidoc generated output
+docs/source/apidoc

docs/readme

@@ -0,0 +1,12 @@
+
+
+# these commands build the docs
+rm -rf build
+rm -rf source/apidoc
+sphinx-apidoc --separate --module-first -d 3 -f -o source/apidoc ../source/fab
+make html
+
+
+# all in one
+rm -rf build && rm -rf source/apidoc && sphinx-apidoc --separate --module-first -d 3 -f -o source/apidoc ../source/fab && make html
+firefox build/html/index.html

docs/source/conf.py

@@ -36,6 +36,7 @@
     'sphinx.ext.graphviz',
     'sphinx.ext.intersphinx',
     'sphinx.ext.autosectionlabel',
+    'sphinx_autodoc_typehints',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -75,3 +76,7 @@
 
 # create linkable targets from section headings
 autosectionlabel_prefix_document = True
+
+
+# include default values in argument descriptions
+typehints_defaults = 'braces-after'

docs/source/glossary.rst

@@ -9,11 +9,11 @@ Glossary
 
     Artefact Store
         At the start of a build run, Fab creates an empty ``artefact_store``.
-        An entry in this store is called a :term:`Named Collection`, which is a mapping from a name string
+        An entry in this store is called an :term:`Artefact Collection`, which is a mapping from a name string
         to, usually, a collection of :term:`Artefact` - but can be anything.
 
         Fab passes the growing artefact store to each step in turn,
-        where they typically read a :term:`Named Collection` and create a new one for subsequent steps to read.
+        where they typically read an :term:`Artefact Collection` and create a new one for subsequent steps to read.
 
         See also :ref:`Artefacts Overview <artefacts_overview>`
 
@@ -43,7 +43,7 @@ Glossary
         Fab's built-in steps come with sensible defaults so the user doesn't have to write unnecessary config.
 
         As an example, the Fortran preprocessor has a default artefact getter which reads *".F90"* files
-        from the :term:`Named Collection` called _"all_source"_.
+        from the :term:`Artefact Collection` called _"all_source"_.
 
         Artefact getters are derived from :class:`~fab.artefacts.ArtefactsGetter`.
 

docs/source/index.rst

@@ -27,3 +27,5 @@ Indices and tables
    Api Reference <apidoc/modules>
    development
    glossary
+   genindex
+   modindex

docs/source/overview.rst

@@ -42,7 +42,7 @@ Example Config
 ==============
 
 Build configs are written in Python. Fab is designed to minimise user input by
-by providing sensible defaults::
+by providing sensible defaults.
 
 .. code-block::
 

setup.py

@@ -47,7 +47,8 @@
     python_requires='>=3.7, <4',
     install_requires=['fparser', 'svn'],
     extras_require={
-        'dev': ['flake8', 'mypy'],
-        'tests': ['pytest', 'pytest-cov', 'pytest-mock']
+        'dev': ['flake8', 'mypy', 'sphinx-autodoc-typehints'],
+        'tests': ['pytest', 'pytest-cov', 'pytest-mock'],
+        'docs': ['sphinx-autodoc-typehints'],
     }
 )

source/fab/build_config.py

@@ -34,23 +34,23 @@ class BuildConfig(object):
     """
 
     def __init__(self, project_label: str, source_root: Optional[Path] = None, steps: Optional[List[Step]] = None,
-                 multiprocessing=True, n_procs: int = None, reuse_artefacts=False,
-                 fab_workspace: Optional[Path] = None, verbose=False, prebuild_folder: Optional[Path] = None):
+                 multiprocessing: bool = True, n_procs: int = None, reuse_artefacts: bool = False,
+                 fab_workspace: Optional[Path] = None, verbose: bool = False, prebuild_folder: Optional[Path] = None):
         """
-        :param str project_label:
+        :param project_label:
             Name of the build project. The project workspace folder is created from this name, with spaces replaced
             by underscores.
-        :param Path source_root:
+        :param source_root:
             Optional argument to allow the config to find source code outside it's project workspace.
             This is useful, for example, when the :py:mod:`fab.steps.grab <grab>` is in a separate script to be run
             less frequently. In this scenario, the source code will be found in a different project workspace folder.
-        :param List[Step] steps:
+        :param steps:
             The list of build steps to run.
-        :param bool multiprocessing:
+        :param multiprocessing:
             An option to disable multiprocessing to aid debugging.
-        :param int n_procs:
+        :param n_procs:
             The number of cores to use for multiprocessing operations. Defaults to the number of available cores.
-        :param bool reuse_artefacts:
+        :param reuse_artefacts:
             A flag to avoid reprocessing certain files on subsequent runs.
             WARNING: Currently unsophisticated, this flag should only be used by Fab developers.
             The logic behind flag will soon be improved, in a work package called "incremental build".