Generate documentation from docstrings

CONTRIBUTING.md

@@ -3,6 +3,8 @@
 - [2) How to make and test code changes](#2-how-to-make-and-test-code-changes)
 - [3) Developer Process for Contributing](#3-developer-process-for-contributing)
 - [4) Release Process](#4-release-process)
+- [5) Update Documentation](#5-update-documentation)
+
 
 ## 1) Introduction
 
@@ -148,4 +150,18 @@ For a new release: <br>
 > - Updated cli-test.yml by @laurencejackson in #195
 > - Release/0.5.2 by @tomaroberts in #196
 
+## 5) Update Documentation
 
+Create rst files describing the structure of the hazen Python Package
+```
+# in an active hazen virtual environment in the root of the project
+# the command below specifies that sphinx should look for scripts in the hazenlib folder
+# and output rst files into the docs/source folder
+sphinx-apidoc -o docs/source hazenlib
+
+# next, from within the docs/ folder
+cd docs/
+# create/update the html files for the documentation
+make html  -f Makefile
+# opening the docs/source/index.html in a web browser allows a preview of the generated docs
+```

docs/source/conf.py

@@ -12,16 +12,15 @@
 #
 import os
 import sys
-from hazenlib import __version__
-
 sys.path.insert(0, os.path.abspath("../.."))
+from hazenlib._version import __version__
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'hazen'
-copyright = '2022, Haris Shuaib'
-author = 'Haris Shuaib'
+project = "hazen"
+copyright = "2022, Haris Shuaib"
+author = "Haris Shuaib"
 
 # The full version, including alpha/beta/rc tags
 release = __version__
@@ -32,22 +31,30 @@
 # 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',
-              'sphinx.ext.viewcode',
-              'sphinx.ext.autosummary',
-              'sphinx.ext.napoleon',  # NumPy and Google docstrings
-              'sphinx.ext.doctest',
-              'sphinx.ext.todo',
-              'sphinx.ext.coverage',
-              'sphinx.ext.ifconfig',
-              'sphinxcontrib.bibtex'
-              ]
-napoleon_google_docstring = False
-napoleon_use_param = False
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",  # NumPy and Google docstrings
+    "sphinx.ext.doctest",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.ifconfig",
+    "sphinxcontrib.bibtex",
+]
+
+napoleon_google_docstring = True
+napoleon_use_param = True
 napoleon_use_ivar = True
-bibtex_bibfiles = ['references.bib']
+napoleon_use_rtype = True
+napoleon_use_keyword = True
+napoleon_custom_sections = None
+autodoc_member_order = "bysource"
+
+bibtex_bibfiles = ["references.bib"]
+
 # 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.
@@ -60,25 +67,25 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 html_theme_options = {
-    'analytics_id': '',  #  Provided by Google in your dashboard
-    'analytics_anonymize_ip': False,
-    'logo_only': False,
-    'display_version': True,
-    'prev_next_buttons_location': 'bottom',
-    'style_external_links': False,
-    'vcs_pageview_mode': '',
-    'style_nav_header_background': '',
+    "analytics_id": "",  #  Provided by Google in your dashboard
+    "analytics_anonymize_ip": False,
+    "logo_only": False,
+    "display_version": True,
+    "prev_next_buttons_location": "bottom",
+    "style_external_links": False,
+    "vcs_pageview_mode": "",
+    "style_nav_header_background": "",
     # Toc options
-    'collapse_navigation': True,
-    'sticky_navigation': True,
-    'navigation_depth': 4,
-    'includehidden': True,
-    'titles_only': False
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
 }
 
 # 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"]

docs/source/contributors.rst

@@ -16,3 +16,4 @@ Contributors
 * `Elizabeth Stamou <https://github.com/elizaGSTT>`_
 * `Francesco Padormo <https://github.com/francescopadormo>`_
 * `Sian Culley <https://github.com/superresolusian>`_
+* `Molly Buckley <https://github.com/mollybuckley>`_

docs/source/hazenlib.rst

@@ -0,0 +1,62 @@
+hazenlib package
+================
+
+Core functions
+-----------------
+
+.. automodule:: hazenlib
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Task-specific functions
+------------------------
+
+.. toctree::
+   :maxdepth: 4
+
+   hazenlib.tasks.acr
+   hazenlib.tasks.magnet
+
+Utility functions:
+-------------------
+
+hazenlib.ACRObject
+-------------------
+
+.. automodule:: hazenlib.ACRObject
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.HazenTask
+-------------------
+
+.. automodule:: hazenlib.HazenTask
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.exceptions
+--------------------------
+
+.. automodule:: hazenlib.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.logger
+----------------------
+
+.. automodule:: hazenlib.logger
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.utils
+---------------------
+
+.. automodule:: hazenlib.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/hazenlib.tasks.acr.rst

@@ -0,0 +1,58 @@
+hazenlib ACR tasks
+===================
+
+hazenlib.tasks.acr\_geometric\_accuracy task
+----------------------------------------------
+
+.. automodule:: hazenlib.tasks.acr_geometric_accuracy
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.acr\_ghosting task
+-----------------------------------
+
+.. automodule:: hazenlib.tasks.acr_ghosting
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.acr\_slice\_position task
+------------------------------------------
+
+.. automodule:: hazenlib.tasks.acr_slice_position
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.acr\_slice\_thickness task
+-------------------------------------------
+
+.. automodule:: hazenlib.tasks.acr_slice_thickness
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.acr\_snr task
+------------------------------
+
+.. automodule:: hazenlib.tasks.acr_snr
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.acr\_spatial\_resolution task
+----------------------------------------------
+
+.. automodule:: hazenlib.tasks.acr_spatial_resolution
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.acr\_uniformity task
+-------------------------------------
+
+.. automodule:: hazenlib.tasks.acr_uniformity
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/hazenlib.tasks.magnet.rst

@@ -0,0 +1,66 @@
+hazenlib MagNet tasks
+=======================
+
+hazenlib.tasks.ghosting task
+------------------------------
+
+.. automodule:: hazenlib.tasks.ghosting
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. hazenlib.tasks.relaxometry task
+.. ---------------------------------
+
+.. .. automodule:: hazenlib.tasks.relaxometry
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
+
+hazenlib.tasks.slice\_position task
+-------------------------------------
+
+.. automodule:: hazenlib.tasks.slice_position
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.slice\_width task
+----------------------------------
+
+.. automodule:: hazenlib.tasks.slice_width
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.snr task
+-------------------------
+
+.. automodule:: hazenlib.tasks.snr
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.snr\_map task
+------------------------------
+
+.. automodule:: hazenlib.tasks.snr_map
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.spatial\_resolution task
+-----------------------------------------
+
+.. automodule:: hazenlib.tasks.spatial_resolution
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+hazenlib.tasks.uniformity task
+--------------------------------
+
+.. automodule:: hazenlib.tasks.uniformity
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/index.rst

@@ -32,6 +32,7 @@ We have also built an interactive web-based implementation of *hazen*, which is
 
    gettingstarted
    tasks
+   hazenlib
    getinvolved
    contributors
 

docs/source/modules.rst

@@ -0,0 +1,7 @@
+hazenlib
+========
+
+.. toctree::
+   :maxdepth: 4
+
+   hazenlib