DOC: Fix Sphinx documentation

Fix Sphinx documentation: - Add a pre-build task to the `readthedocs` config file in order to generate the `rst` files from the package docstrings so that Sphinx build the HTML files from them. - Add the `napoleon` extension to the Sphinx config file so that it can parse NumPy and Google style docstrings. - Fix the `index.rst` file so that the package API is effectively displayed: set `whitematterpackage` as the entry for the reference section. - Set the `bin` and `utilities` packages as the entries for the scripts section in the `index.rst` file.
SlicerDMRI · Oct 24, 2023 · 7acafa0 · 7acafa0
1 parent 6bd4a22
commit 7acafa0
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 0 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -13,6 +13,9 @@ build:
   apt_packages:
     - libblas-dev
     - liblapack-dev
+  jobs:
+    pre_build:
+      - sphinx-apidoc -f -o doc .
 
 # Build documentation in the doc/ directory with Sphinx
 sphinx:

diff --git a/doc/conf.py b/doc/conf.py
@@ -67,6 +67,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/doc/index.rst b/doc/index.rst
@@ -1,8 +1,16 @@
 Welcome to the whitematteranalysis documentation!
 =================================================
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference
+
+   whitematteranalysis
+
 .. toctree::
     :maxdepth: 1
+    :caption: Scripts
 
     bin
     utilities
+