[FIX][DOC] fix doc build (#19)

* make it work * build doc on every pr * use autosummary * silence gallery * Update docs/Makefile
paquiteau · Oct 7, 2024 · 0295124 · 0295124
1 parent 1bca434
commit 0295124
Show file tree

Hide file tree

Showing 14 changed files with 68 additions and 39 deletions.
diff --git a/.github/workflows/master-cd.yml b/.github/workflows/master-cd.yml
@@ -64,22 +64,21 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.12"
       - name: Install dependencies
         shell: bash -l {0}
         run: |
           python -m pip install --upgrade pip
           python -m pip install .[optional,doc]
 
       - name: Build API documentation
-        run: |
-          python -m sphinx docs docs_build
+        run: make -C docs html
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           # Upload entire repository
-          path: 'docs_build'
+          path: 'build'
 
       - name: Deploy to GitHub Pages
         id: deployment

diff --git a/.github/workflows/test-ci.yml b/.github/workflows/test-ci.yml
@@ -28,6 +28,30 @@ jobs:
         shell: bash
         run: ruff check src
 
+  makedocs:
+    name: build documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Get history and tags for SCM versioning to work
+        run: |
+          git fetch --prune --unshallow
+          git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        shell: bash -l {0}
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[optional,doc]
+
+      - name: Build API documentation
+        run: make -C docs html
+
   codespell:
     name: Check for spelling errors
     runs-on: ubuntu-latest

diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 .DS_Store
 .idea
 *.log
+sg_execution_times.rst
 tmp/
 
 *_cache/

diff --git a/README.rst b/README.rst
@@ -46,6 +46,10 @@ A mathematical description of these methods is available in the documentation.
 Installation
 ============
 
+.. code::
+
+   $ pip install patch-denoise
+
 patch-denoise requires Python>=3.9
 
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -3,9 +3,9 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= --verbose
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
+SOURCEDIR     = 
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
@@ -14,6 +14,10 @@ help:
 
 .PHONY: help Makefile
 
+clean:
+	rm -fr build auto_examples _autosummary
+	rm -f sg_execution_times.rst
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

diff --git a/docs/api.rst b/docs/api.rst
@@ -2,8 +2,8 @@ API Reference
 =============
 
 .. autosummary::
-   :toctree: _autosummary
-   :template: custom-module-template.rst
-   :recursive:
+    :toctree: _autosummary
+    :template: custom-module-template.rst
+    :recursive:
 
     patch_denoise
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,7 +16,7 @@
 import sys
 from importlib.metadata import version
 
-sys.path.insert(0, os.path.abspath("../.."))  # Source code dir relative to this file
+sys.path.insert(0, os.path.abspath(".."))  # Source code dir relative to this file
 
 # -- Project information -----------------------------------------------------
 
@@ -42,7 +42,8 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
-    "sphinx_gallery.gen_gallery",
+    # "sphinx_gallery.gen_gallery",
+    "sphinxarg.ext"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -51,8 +52,16 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["build", "Thumbs.db", ".DS_Store"]
 
+_python_doc_base = "https://docs.python.org/3.9"
+
+intersphinx_mapping = {
+    "python": (_python_doc_base, None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://scipy.github.io/devdocs/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+}
 
 # generate autosummary even if no references
 autosummary_generate = True
@@ -66,7 +75,9 @@
 sphinx_gallery_conf = {
     "examples_dirs": ["../examples/"],
     "filename_pattern": "/example_",
-    "ignore_pattern": r"/(__init__|conftest)\.py",
+    'ignore_pattern': 'conftest.py',
+    'example_extensions': {'.py'},    
+    "gallery_dirs" : ["auto_examples"],
     "reference_url": {
         "numpy": "http://docs.scipy.org/doc/numpy-1.9.1",
         "scipy": "http://docs.scipy.org/doc/scipy-0.17.0/reference",
@@ -85,5 +96,5 @@
 # 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 = []
 html_context = {"default_mode": "light"}
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,5 +12,6 @@
 
    api
    denoisers
-   auto_examples/index
    usage
+
+   .. auto_examples/index
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -1,6 +1,6 @@
-#########################################
-Using patch-denoise from the command line
-#########################################
+############
+Command line
+############
 
 ``patch-denoise`` minimally requires a path to a NIfTI file,
 but it can take advantage of reconstructed phase data and/or noise volumes.

diff --git a/examples/__init__.py b/examples/__init__.py
diff --git a/examples/example_experimental_data.py b/examples/example_experimental_data.py
@@ -1,22 +1,6 @@
 """
 Experimental Data denoising
 ===========================
-
-This is a example script to test various denoising methods on real-word fMRI data.
-
-Source data should a sequence of 2D or 3D data, the temporal dimension being the last one.
-
-The available denoising methods are "nordic", "mp-pca", "hybrid-pca", "opt-fro", "opt-nuc" and "opt-op".
 """
 
-from patch_denoise.simulation.phantom import mr_shepp_logan_t2_star, g_factor_map
-from patch_denoise.simulation.activations import add_frames
-from patch_denoise.simulation.noise import add_temporal_gaussian_noise
-
-# %%
-# Setup the parameters for the simulation and noise
-
-SHAPE = (64, 64, 64)
-N_FRAMES = 200
 
-NOISE_LEVEL = 2
diff --git a/pyproject.toml b/pyproject.toml
@@ -34,6 +34,7 @@ doc = [
   "pydata-sphinx-theme",
   "numpydoc",
   "sphinx_gallery",
+  "sphinx-argparse",
   "sphinx",
 ]
 

diff --git a/src/patch_denoise/bindings/__init__.py b/src/patch_denoise/bindings/__init__.py
@@ -2,7 +2,8 @@
 
 3 Bindings are available:
 
-* A `Nipype`<https://github.com/nipype/nipype/>_ binding
-* A `Modopt`<https://cea-cosmic.github.io/ModOpt/index.html>_ binding
-* A Command line interface, available as ``patch-denoise`` after installation.
+- A `Nipype <https://github.com/nipype/nipype/>`_ binding
+- A `Modopt <https://cea-cosmic.github.io/ModOpt/index.html>`_ binding
+- A Command line interface, available as ``patch-denoise`` after installation.
+
 """
diff --git a/src/patch_denoise/denoise.py b/src/patch_denoise/denoise.py
@@ -89,7 +89,7 @@ def hybrid_pca(
     References
     ----------
     .. [#]
-    https://submissions.mirasmart.com/ISMRM2022/Itinerary/Files/PDFFiles/2688.html
+        https://submissions.mirasmart.com/ISMRM2022/Itinerary/Files/PDFFiles/2688.html
 
     See Also
     --------