fix: build docs on CircleCI

Author: oesteban

.circleci/config.yml

@@ -377,7 +377,7 @@ jobs:
             python -m venv /tmp/venv
             source /tmp/venv/bin/activate
             python -m pip install -U build hatch hatchling pip twine docutils
-            python -m pip install --no-cache-dir -r docs/requirements.txt
+            python -m pip install .[docs]
       - run:
           name: Build only this commit
           command: |

docs/Makefile

@@ -4,6 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
+SPHINX_APIDOC_OPTIONS = members,show-inheritance
 PAPER         =
 BUILDDIR      = _build
 OUTDIR        = html
@@ -57,7 +58,7 @@ docs-coverage:
 	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
 
 html:
-	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(OUTDIR)
+	PYTHONPATH=$(PYTHONPATH) SPHINX_APIDOC_OPTIONS=$(SPHINX_APIDOC_OPTIONS) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(OUTDIR)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/$(OUTDIR)."
 

sdcflows/data/config-example.toml renamed to docs/_static/config-example.toml

@@ -7,6 +7,7 @@ Information on specific functions, classes, and methods.
    :glob:
 
    api/sdcflows.cli
+   api/sdcflows.config
    api/sdcflows.data
    api/sdcflows.fieldmaps
    api/sdcflows.interfaces

docs/api.rst

@@ -7,7 +7,7 @@ matplotlib >= 2.2.0
 nbsphinx
 nibabel
 nipype >= 1.5.1
-niworkflows ~= 1.6.3
+niworkflows >= 1.7.0
 numpy
 packaging
 pandoc
@@ -18,4 +18,4 @@ sphinx >= 7.2.2
 sphinx-argparse
 sphinxcontrib-apidoc
 templateflow
-traits < 6.4
+traits < 6.4

docs/requirements.txt

@@ -47,19 +47,24 @@ doc = [
     "attrs >= 20.1.0",
     "furo",
     "importlib_resources",
+    "ipykernel",
+    "ipython",
     "matplotlib >= 2.2.0",
+    "nbsphinx",
     "nibabel",
     "nipype >= 1.5.1",
-    "traits < 6.4",
     "niworkflows >= 1.7.0",
     "numpy",
     "packaging",
+    "pandoc",
     "pydot >= 1.2.3",
     "pydotplus",
+    "scipy",
     "sphinx >= 7.2.2",
     "sphinx-argparse",
     "sphinxcontrib-apidoc",
-    "templateflow"
+    "templateflow",
+    "traits < 6.4"
 ]
 
 mem = [

pyproject.toml

@@ -54,7 +54,7 @@
 The module has a :py:func:`~sdcflows.config.to_filename` function to allow writing out
 the settings to hard disk in *ToML* format, which looks like:
 
-.. literalinclude:: ../sdcflows/data/config-example.toml
+.. literalinclude:: /_static/config-example.toml
    :language: toml
    :name: sdcflows.toml
    :caption: **Example file representation of SDCFlows settings**.
@@ -65,13 +65,13 @@
 Configuration sections
 ----------------------
 .. autoclass:: environment
-   :members:
+    :noindex:
 .. autoclass:: execution
-   :members:
+    :noindex:
 .. autoclass:: workflow
-   :members:
+    :noindex:
 .. autoclass:: nipype
-   :members:
+    :noindex:
 
 Usage
 -----
@@ -97,7 +97,7 @@
 Logging
 -------
 .. autoclass:: loggers
-   :members:
+   :noindex:
 
 Other responsibilities
 ----------------------