Merge pull request #121 from eurunuela/docs_example

Improvements to the docs

docs/_static/theme_overrides.css

@@ -1,20 +1,28 @@
 /* override table width restrictions */
 @media screen and (min-width: 767px) {
-
-   .wy-table-responsive table td {
-      /* !important prevents the common CSS stylesheets from overriding
+  .wy-table-responsive table td {
+    /* !important prevents the common CSS stylesheets from overriding
          this as on RTD they are loaded after this stylesheet */
-      white-space: normal !important;
-   }
+    white-space: normal !important;
+  }
 
-   .wy-table-responsive {
-      overflow: visible !important;
-   }
+  .wy-table-responsive {
+    overflow: visible !important;
+  }
 }
 
 div.admonition.caution {
-  background: #FFC3C3
+  background: #ffc3c3;
 }
 .rst-content .caution .admonition-title {
-  background: #FF6F6F
+  background: #ff6f6f;
+}
+
+:root {
+  --pst-color-primary: #b672da !important;
+  --pst-color-link: #b672da !important;
+  --pst-color-link-hover: #8c41af !important;
+  --bs-link-color: #b672da !important;
+  --bs-link-hover-color: #8c41af !important;
+  --pst-color-inline-code-links: #46594f !important;
 }

docs/api.md

@@ -1,108 +1,14 @@
 (api-ref)=
 
-```{eval-rst}
-.. currentmodule:: pySPFM
-```
-
-# API
-
-(api-pyspfm-ref)=
-
-## {mod}`pySPFM.workflows`: The main pySPFM workflow
-
-```{eval-rst}
-.. automodule:: pySPFM.workflows
-   :no-members:
-   :no-inherited-members:
-```
-
-```{eval-rst}
-.. currentmodule:: pySPFM.workflows
-```
-
-```{eval-rst}
-.. autosummary::
-   :toctree: generated/
-   :template: module.rst
-
-   pySPFM.workflows.pySPFM
-   pySPFM.workflows.auc_to_estimates
-```
-
-(api-deconvolution-ref)=
-
-## {mod}`pySPFM.deconvolution`: Deconvolution methods
-
-```{eval-rst}
-.. automodule:: pySPFM.deconvolution
-   :no-members:
-   :no-inherited-members:
-```
-
-```{eval-rst}
-.. currentmodule:: pySPFM.deconvolution
-```
-
-```{eval-rst}
-.. autosummary::
-   :toctree: generated/
-   :template: function.rst
-
-   pySPFM.deconvolution.debiasing
-   pySPFM.deconvolution.fista
-   pySPFM.deconvolution.hrf_generator
-   pySPFM.deconvolution.lars
-   pySPFM.deconvolution.select_lambda
-   pySPFM.deconvolution.spatial_regularization
-   pySPFM.deconvolution.stability_selection
-
-```
-
-(api-io-ref)=
-
-## {mod}`pySPFM.io`: Input/Output methods
-
-```{eval-rst}
-.. automodule:: pySPFM.io
-   :no-members:
-   :no-inherited-members:
-```
-
-```{eval-rst}
-.. currentmodule:: pySPFM.io
-```
-
-```{eval-rst}
-.. autosummary::
-   :toctree: generated/
-   :template: function.rst
-
-   pySPFM.io.read_data
-   pySPFM.io.update_header
-   pySPFM.io.write_data
-   pySPFM.io.write_json
-
-```
-
-(api-utils-ref)=
-
-## {mod}`pySPFM.utils`: Miscellaneous utility methods
-
-```{eval-rst}
-.. automodule:: pySPFM.utils
-   :no-members:
-   :no-inherited-members:
-```
-
-```{eval-rst}
-.. currentmodule:: pySPFM.utils
-```
-
-```{eval-rst}
-.. autosummary::
-   :toctree: generated/
-   :template: module.rst
-
-   pySPFM.utils.setup_loggers
-   pySPFM.utils.teardown_loggers
+# API Reference
+
+```{toctree}
+---
+maxdepth: 2
+caption: API Documentation
+---
+api/workflows
+api/deconvolution
+api/io
+api/utils
 ```

docs/api/deconvolution.md

@@ -0,0 +1,18 @@
+
+# Deconvolution
+
+```{eval-rst}
+.. currentmodule:: pySPFM.deconvolution
+
+.. autosummary::
+   :toctree: ../generated/
+   :template: module.rst
+
+   debiasing
+   fista
+   hrf_generator
+   lars
+   select_lambda
+   spatial_regularization
+   stability_selection
+```

docs/api/io.md

@@ -0,0 +1,14 @@
+# Input/Output
+
+```{eval-rst}
+.. currentmodule:: pySPFM.io
+
+.. autosummary::
+   :toctree: ../generated/
+   :template: module.rst
+
+   read_data
+   update_header
+   write_data
+   write_json
+```

docs/api/utils.md

@@ -0,0 +1,12 @@
+# Utilities
+
+```{eval-rst}
+.. currentmodule:: pySPFM.utils
+
+.. autosummary::
+   :toctree: ../generated/
+   :template: module.rst
+
+   setup_loggers
+   teardown_loggers
+```

docs/api/workflows.md

@@ -0,0 +1,12 @@
+# Workflows
+
+```{eval-rst}
+.. currentmodule:: pySPFM.workflows
+
+.. autosummary::
+   :toctree: ../generated/
+   :template: module.rst
+
+   pySPFM
+   auc_to_estimates
+```

docs/conf.py

@@ -39,7 +39,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "ipykernel",
+    # "ipykernel",
     "matplotlib.sphinxext.plot_directive",
     # "myst_parser",
     "myst_nb",
@@ -51,12 +51,33 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
-    # "sphinx.ext.mathjax",
+    "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
+    # "sphinx_gallery",
     "sphinx_gallery.load_style",
 ]
 
+myst_enable_extensions = [
+    "colon_fence",
+    "dollarmath",
+]
+
+
+# Update mime priority configuration with integer priorities
+nb_mime_priority_overrides = [
+    ("html", "application/vnd.plotly.v1+json", 10),  # Format: (format, mimetype, priority)
+    ("html", "text/html", 5),
+    ("html", "image/svg+xml", 4),
+    ("html", "image/png", 3),
+    ("html", "image/jpeg", 2),
+    ("html", "text/plain", 1),
+]
+
+# Keep plotly plugin configuration
+# nb_render_plugin = "plotly"
+
+
 from distutils.version import LooseVersion
 
 import sphinx
@@ -137,18 +158,31 @@
 
 html_theme = "sphinx_book_theme"
 
+# Configure TOC settings
+toc_object_entries_show_parents = "hide"
+
+# Add autosummary settings to control display names
+autosummary_member_order = "groupwise"
+add_module_names = False  # Don't prefix module names
+modindex_common_prefix = ["pySPFM."]  # Remove common prefix from module index
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 
+
 html_theme_options = {
-    "includehidden": False,
+    "show_nav_level": 2,
+    "collapse_navigation": True,
+    "navigation_depth": 4,
+    "show_toc_level": 2,
 }
 
 # 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_css_files = ["theme_overrides.css"]
 
 
 def setup(app):
@@ -178,5 +212,7 @@ def setup(app):
     "matplotlib": ("https://matplotlib.org/", None),
     "nibabel": ("https://nipy.org/nibabel/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
-    "nilearn": ("http://nilearn.github.io/", None),
+    "nilearn": ("http://nilearn.github.io/stable/", None),
 }
+
+html_js_files = ["https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"]

docs/examples.md

@@ -1,6 +1,7 @@
 # Examples
 
-```{nbgallery}
-notebooks/examples.ipynb
+This is an example.
 
-```
+<!-- ```{glue:} regularization_figure
+:doc: notebooks/examples.ipynb
+``` -->

docs/notebooks/examples.ipynb

@@ -10,7 +10,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 103,
+   "execution_count": null,
    "id": "f215440b-fc20-4d7d-b3ee-c55f9cba35a8",
    "metadata": {},
    "outputs": [],
@@ -21,7 +21,9 @@
     "\n",
     "from pySPFM.deconvolution.hrf_generator import HRFMatrix\n",
     "from pySPFM.deconvolution.lars import solve_regularization_path\n",
-    "import matplotlib.pyplot as plt"
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "from myst_nb import glue"
    ]
   },
   {
@@ -543,7 +545,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 127,
+   "execution_count": null,
    "id": "6f58e999-d740-4b86-975b-6023f2ca81d4",
    "metadata": {},
    "outputs": [
@@ -1754835,7 +1754837,8 @@
     "    yaxis=dict(title='Amplitude'),\n",
     ")\n",
     "\n",
-    "fig.show()"
+    "glue(\"regularization_figure\", fig, display=False)\n",
+    "# fig.show()"
    ]
   },
   {

docs/usage.md

@@ -10,26 +10,26 @@ The fixed $\lambda$ method is the simplest one. It consists in choosing one of t
 to automatically calculate the regularization parameter lambda:
 
 - `universal threshold`:
-  : $\lambda = \sigma * \sqrt{2 * \log(T)}$, where $\sigma$ is the median absolute
-    deviation of the estimated level of noise and T is the number of TRs.
+  $\lambda = \sigma * \sqrt{2 * \log(T)}$, where $\sigma$ is the median absolute
+  deviation of the estimated level of noise and T is the number of TRs.
 - `lower universal threshold`:
-  : $\lambda = \sigma * \sqrt{2 * \log(T) - \log(1 + 4 * \log(T))}$, where $\sigma$
-    is the median absolute deviation of the estimated level of noise and T is the number of TRs.
+  $\lambda = \sigma * \sqrt{2 * \log(T) - \log(1 + 4 * \log(T))}$, where $\sigma$
+  is the median absolute deviation of the estimated level of noise and T is the number of TRs.
 - `median absolute deviation`:
-  : Calculate lambda as the median absolute deviation of fine-scale wavelet coefficients
-    (Daubechies, order 3). For more information, see [Karahanoglu et al. (2013)].
+  Calculate lambda as the median absolute deviation of fine-scale wavelet coefficients
+  (Daubechies, order 3). For more information, see [Karahanoglu et al. (2013)].
 - `updating median absolute deviation`:
-  : Median absolute deviation of the estimated level of the noise that gets updated on each
-    iteration (see [Karahanoglu et al. (2013)]):
-    $\lambda_{n+1} = {\frac{N \sigma}{\frac{1}{2} \| \mathbf{y} - \mathbf{Hs} \|_2^2 \lambda_n}}$.
+  Median absolute deviation of the estimated level of the noise that gets updated on each
+  iteration (see [Karahanoglu et al. (2013)]):
+  $\lambda_{n+1} = {\frac{N \sigma}{\frac{1}{2} \| \mathbf{y} - \mathbf{Hs} \|_2^2 \lambda_n}}$.
 - `percentage of maximum lambda`:
-  : percentage of the maximum lambda possible to use as lambda.
-    $\lambda = \textrm{pcg} * \lambda_{max}$,
-    where $\lambda_{max}= \| \mathbf{H}^T \mathbf{y} \|$ and
-    $0 \leq \textrm{pcg} \leq 1$
+  percentage of the maximum lambda possible to use as lambda.
+  $\lambda = \textrm{pcg} * \lambda_{max}$,
+  where $\lambda_{max}= \| \mathbf{H}^T \mathbf{y} \|$ and
+  $0 \leq \textrm{pcg} \leq 1$
 - `factor of median absolute deviation`:
-  : factor of the estimate of the level of noise to use as lambda.
-    $\lambda = \textrm{factor} * \sigma, with 0 \leq \textrm{factor} \leq 1$
+  factor of the estimate of the level of noise to use as lambda.
+  $\lambda = \textrm{factor} * \sigma, with 0 \leq \textrm{factor} \leq 1$
 
 ```bash
 pySPFM -i my_echo_1.nii.gz my_echo_3.nii.gz my_echo_3.nii.gz -m my_mask.nii.gz