Merge pull request #151 from openspyrit/doc_auto

Doc auto is working

.readthedocs.yml

@@ -5,18 +5,18 @@
 # Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/source/conf.py
-
 # Optionally build your docs in additional formats such as PDF
 formats: all # pdf, epub and htlmzip
 
 # Optionally set the version of Python and requirements required to build your docs
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.11"
 python:
   install:
     - requirements: requirements.txt
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py

docs/source/_templates/spyrit-class-template.rst

@@ -3,19 +3,19 @@
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
-   :members:
    :show-inheritance:
-   :inherited-members:
 
    {% block methods %}
-   .. automethod:: __init__
-
    {% if methods %}
    .. rubric:: {{ _('Methods') }}
 
    .. autosummary::
+      :toctree:
+      :template: spyrit-method-template.rst
    {% for item in methods %}
+   {%- if item is in members %}
       ~{{ name }}.{{ item }}
+   {%- endif %}
    {%- endfor %}
    {% endif %}
    {% endblock %}
@@ -25,8 +25,11 @@
    .. rubric:: {{ _('Attributes') }}
 
    .. autosummary::
+      :toctree:
    {% for item in attributes %}
+   {%- if item != "training" %}
       ~{{ name }}.{{ item }}
+   {%- endif %}
    {%- endfor %}
    {% endif %}
    {% endblock %}

docs/source/_templates/spyrit-method-template.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. automethod:: {{ objname }}

docs/source/_templates/spyrit-module-template.rst

@@ -1,6 +1,7 @@
 {{ fullname | escape | underline}}
 
 .. automodule:: {{ fullname }}
+   :show-inheritance:
 
    {% block attributes %}
    {% if attributes %}

docs/source/conf.py

@@ -14,12 +14,10 @@
 import sys
 from sphinx_gallery.sorting import ExampleTitleSortKey
 
-sys.path.insert(0, os.path.abspath("../../spyrit"))
-sys.path.insert(0, os.path.abspath("../../"))
-
+# paths relative to this file
+sys.path.insert(0, os.path.abspath("../.."))
 
 # -- Project information -----------------------------------------------------
-
 project = "spyrit"
 copyright = "2021, Antonio Tomas Lorente Mur - Nicolas Ducros - Sebastien Crombez - Thomas Baudier"
 author = (
@@ -29,18 +27,17 @@
 # The full version, including alpha/beta/rc tags
 release = "2.1.0"
 
-
 # -- General configuration ---------------------------------------------------
 
 # 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.intersphinx",
-    "sphinx.ext.autodoc",  #
+    "sphinx.ext.autodoc",
     "sphinx.ext.mathjax",
     "sphinx.ext.todo",
-    "sphinx.ext.autosummary",  #
+    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_gallery.gen_gallery",
@@ -59,6 +56,8 @@
 napoleon_use_param = False
 napoleon_use_rtype = False
 
+autodoc_member_order = "bysource"
+autosummary_generate = True
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
@@ -72,7 +71,7 @@
 sphinx_gallery_conf = {
     # path to your examples scripts
     "examples_dirs": [
-        "../../spyrit/tutorial",
+        "../../tutorial",
     ],
     # path where to save gallery generated examples
     "gallery_dirs": ["gallery"],
@@ -113,5 +112,24 @@
 }
 
 # http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports
-autodoc_mock_imports = "numpy matplotlib mpl_toolkits scipy torch torchvision Pillow opencv-python imutils PyWavelets pywt wget imageio".split()
-autodoc_member_order = "bysource"
+# autodoc_mock_imports incompatible with autosummary somehow
+# autodoc_mock_imports = "numpy matplotlib mpl_toolkits scipy torch torchvision Pillow opencv-python imutils PyWavelets pywt wget imageio".split()
+
+
+# exclude all torch.nn.Module members from the documentation
+# except forward and __init__ methods
+import torch
+
+
+def skip_member_handler(app, what, name, obj, skip, options):
+    if name in [
+        "forward",
+    ]:
+        return False
+    if name in dir(torch.nn.Module):
+        return True
+    return None
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip_member_handler)

docs/source/index.rst

@@ -98,7 +98,6 @@ The main functionalities of SPyRiT are implemented in the :class:`spyrit.core` s
 
 6. **Training (train)** provide the functionalities for training reconstruction networks (see :mod:`spyrit.core.train`).
 
-
 Subpackages
 -----------------------------------
 
@@ -117,8 +116,6 @@ Subpackages
 
    gallery/index
 
-
-
 .. Indices and tables
     ==================
 

spyrit/tutorial/tuto_01_acquisition_operators.py → tutorial/tuto_01_acquisition_operators.py

@@ -2,6 +2,7 @@
 01. Acquisition operators
 ==========================
 .. _tuto_acquisition_operators:
+
 This tutorial shows how to simulate measurements using the :class:`spyrit.core`
 submodule, which is based on three classes:
 
@@ -14,15 +15,9 @@
 3. **Preprocessing operators** are typically used to process the noisy
    measurements prior to reconstruction (see :mod:`spyrit.core.prep`)
 
-These tutorials must be runned from `spyrit/tutorial/` folder (they load image samples from `spyrit/images/`).
+These tutorials load image samples from `/images/`.
 """
 
-import numpy as np
-import os
-from spyrit.misc.disp import imagesc
-import matplotlib.pyplot as plt
-
-
 # %%
 # Load a batch of images
 # -----------------------------------------------------------------------------
@@ -31,16 +26,20 @@
 # Images :math:`x` for training neural networks expect values in [-1,1]. The images are normalized
 # using the :func:`transform_gray_norm` function.
 
-# sphinx_gallery_thumbnail_path = '../../spyrit/images/tuto/noise_op.png'
+import os
 
-from spyrit.misc.statistics import transform_gray_norm
-import torchvision
 import torch
+import torchvision
+import numpy as np
+import matplotlib.pyplot as plt
+
+from spyrit.misc.disp import imagesc
+from spyrit.misc.statistics import transform_gray_norm
 
 h = 64  # image size hxh
 i = 1  # Image index (modify to change the image)
 spyritPath = os.getcwd()
-imgs_path = os.path.join(spyritPath, "../images")
+imgs_path = os.path.join(spyritPath, "images/")
 
 
 # Create a transform for natural images to normalized grayscale image tensors
@@ -69,10 +68,13 @@
 ###############################################################################
 # Noise operators are defined in the :mod:`~spyrit.core.noise` module. A noise
 # operator computes the following three steps sequentially:
-#   1. Normalization of the image :math:`x` with values in [-1,1] to get an
-#      image :math:`\tilde{x}=\frac{x+1}{2}` in [0,1], as it is required for measurement simulation
-#   2. Application of the measurement model, i.e., computation of :math:`H\tilde{x}`
-#   3. Application of the noise model
+#
+# 1. Normalization of the image :math:`x` with values in [-1,1] to get an image
+# :math:`\tilde{x}=\frac{x+1}{2}` in [0,1], as it is required for measurement simulation
+#
+# 2. Application of the measurement model, i.e., computation of :math:`H\tilde{x}`
+#
+# 3. Application of the noise model
 #
 # .. math::
 #       y \sim \texttt{Noise}(H\tilde{x}) = \texttt{Noise}\left(\frac{H(x+1)}{2}\right),
@@ -215,9 +217,11 @@
 
 ###############################################################################
 # We consider the :class:`spyrit.core.prep.DirectPoisson` class that intends
-# to "undo" the :class:`spyrit.core.noise.Poisson` class by compensating for
-#   * the scaling that appears when computing Poisson-corrupted measurements
-#   * the affine transformation to get images in [0,1] from images in [-1,1]
+# to "undo" the :class:`spyrit.core.noise.Poisson` class by compensating for:
+#
+# * the scaling that appears when computing Poisson-corrupted measurements
+#
+# * the affine transformation to get images in [0,1] from images in [-1,1]
 #
 # For this, it computes
 #
@@ -281,4 +285,6 @@
 # We show again one of the preprocessed measurement vectors (tutorial thumbnail purpose)
 
 # Plot
+# Choose this plot to be the thumbnail
+# sphinx_gallery_thumbnail_number = 5
 imagesc(m2[0, :, :], "100 photons", title_fontsize=20)

spyrit/tutorial/tuto_02_pseudoinverse_linear.py → tutorial/tuto_02_pseudoinverse_linear.py

@@ -2,11 +2,12 @@
 02. Pseudoinverse solution from linear measurements
 ===================================================
 .. _tuto_pseudoinverse_linear:
+
 This tutorial shows how to simulate measurements and perform image reconstruction.
 The measurement operator is chosen as a Hadamard matrix with positive coefficients.
 Note that this matrix can be replaced by any desired matrix.
 
-These tutorials must be runned from `spyrit/tutorial/` folder (they load image samples from `spyrit/images/`).
+These tutorials load image samples from `/images/`.
 """
 
 # %%
@@ -17,18 +18,19 @@
 # Images :math:`x` for training expect values in [-1,1]. The images are normalized
 # using the :func:`transform_gray_norm` function.
 
-# sphinx_gallery_thumbnail_path = '../../spyrit/images/tuto/pinvnet.png'
-
 import os
-from spyrit.misc.statistics import transform_gray_norm
-import torchvision
+
 import torch
+import torchvision
+import numpy as np
+
 from spyrit.misc.disp import imagesc
+from spyrit.misc.statistics import transform_gray_norm
 
 h = 64  # image size hxh
 i = 1  # Image index (modify to change the image)
 spyritPath = os.getcwd()
-imgs_path = os.path.join(spyritPath, "../images")
+imgs_path = os.path.join(spyritPath, "images/")
 
 
 # Create a transform for natural images to normalized grayscale image tensors
@@ -62,13 +64,13 @@
 # image of size :attr:`h` and takes its positive part.
 
 from spyrit.misc.walsh_hadamard import walsh2_matrix
-import numpy as np
 
 F = walsh2_matrix(h)
 F = np.where(F > 0, F, 0)
 
 ###############################################################################
 # .. _low_frequency:
+#
 # Next, we subsample the rows of the measurement matrix to simulate an
 # accelerated acquisition. For this, we use the
 # :func:`spyrit.misc.sampling.Permutation_Matrix` function
@@ -142,11 +144,11 @@
 
 ###############################################################################
 # We now compute and plot the preprocessed measurements corresponding to an
-# image in [-1,1]. For details in the preprocessing, see :ref:`tuto_acquisition_operators`.
+# image in [-1,1]. For details in the preprocessing, see :ref:`Tutorial 1 <sphx_glr_gallery_tuto_01_acquisition_operators.py>`.
 #
 # .. note::
 #
-#       Using :class:`spyrit.core.prep.DirectPoisson` with :math:`\alpha` = 1
+#       Using :class:`spyrit.core.prep.DirectPoisson` with :math:`\alpha = 1`
 #       allows to compensate for the image normalisation achieved by
 #       :class:`spyrit.core.noise.NoNoise`.
 
@@ -181,6 +183,8 @@
 x_rec = recon_op(y, meas_op)
 
 # plot
+# Choose this plot to be the thumbnail
+# sphinx_gallery_thumbnail_number = 5
 x_plot = x_rec.squeeze().view(h, h).cpu().numpy()
 imagesc(x_plot, "Pseudoinverse reconstruction (no noise)", title_fontsize=20)
 
@@ -195,7 +199,7 @@
 # can be set to the identity operator
 
 ###############################################################################
-# .. image:: ../../../spyrit/images/tuto/pinvnet.png
+# .. image:: /spyrit/docs/source/fig/pinvnet.png
 #    :width: 400
 #    :align: center
 #    :alt: Sketch of the PinvNet architecture
@@ -248,7 +252,7 @@
 ###############################################################################
 # Here, we consider the :class:`spyrit.core.noise.Poisson` class
 # together with a :class:`spyrit.core.prep.DirectPoisson`
-# preprocessing operator (see :ref:`tuto_acquisition_operators`).
+# preprocessing operator (see :ref:`Tutorial 1 <sphx_glr_gallery_tuto_01_acquisition_operators.py>`).
 
 alpha = 10  # maximum number of photons in the image