Merge pull request #2031 from kif/2017_doc

Upgrade documentation to the `pydata_sphinx_theme`
silx-kit · Jan 31, 2025 · f0c4223 · f0c4223
2 parents 2f24636 + 7a1dbdf
commit f0c4223
Show file tree

Hide file tree

Showing 19 changed files with 792 additions and 73 deletions.
diff --git a/ci/requirements_rtd.txt b/ci/requirements_rtd.txt
@@ -8,7 +8,7 @@ pygments[plugins]
 sphinxcontrib-programoutput
 silx >= 2
 nbsphinx
-sphinx-rtd-theme
 docutils<0.20
 ipython_genutils
+pydata-sphinx-theme
 importlib_resources; python_version < '3.9'
diff --git a/doc/source/api/pyFAI.rst b/doc/source/api/pyFAI.rst
@@ -10,30 +10,21 @@ pyFAI package
     :show-inheritance:
 
 :mod:`integrator.azimuthal` Module
----------------------------------
+----------------------------------
 
 .. automodule:: pyFAI.integrator.azimuthal
     :members:
     :undoc-members:
     :show-inheritance:
 
 :mod:`integrator.fiber` Module
----------------------------------
+------------------------------
 
 .. automodule:: pyFAI.integrator.fiber
     :members:
     :undoc-members:
     :show-inheritance:
 
-
-:mod:`azimuthalIntegrator` Module
----------------------------------
-
-.. automodule:: pyFAI.azimuthalIntegrator
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`average` Module
 ---------------------
 

diff --git a/doc/source/api/resources/index.rst b/doc/source/api/resources/index.rst
@@ -2,7 +2,7 @@ pyFAI.resources package
 =======================
 
 pyFAI.resources.__init__ module
-----------------------------
+-------------------------------
 
 .. automodule:: pyFAI.resources.__init__
     :members:

diff --git a/doc/source/changelog.rst b/doc/source/changelog.rst
@@ -50,9 +50,12 @@ Change-log of versions
   * New tutorial of usage in doc/source/usage/tutorial/MultiGeometry/MultiGeometryFiber.ipynb`
 
 - Tool to rebin 2d-result into 1d-result (`pyFAI.containers.rebin1d`)
+- `pyFAI-diffmap-view` now displays the motor position in the the map.
+- Change documentation template to `pydata`
 - Several bug-fixes & better code coverage
-- Supports python 3.9 .. 3.13. The GIL-free version on python 3.13 is untested
+- Supports python 3.9 to 3.13. The GIL-free version on python 3.13 is untested.
 - Tested by the developers on Windows (amd64), linux (amd64, arm64 and ppc64le) and MacOS (amd64 and arm64). Thanks to Debian for extending this matrix.
+- More than 500 commits, by Thomas Vincent, Loic Huder,  Edgar Gutierrez Fernandez and Jérôme Kieffer
 
 2024.09 12/09/2024
 ------------------
@@ -90,8 +93,9 @@ Change-log of versions
 
 2024.05 21/05/2024
 ------------------
-- Implemented unweighted average for 2D integration
- + Integration engines now handle the boolean 'weighted_average' to switch to unweighted mean, similar to legacy methods
+- Implemented unweighted average for 2D integration:
+  + Integration engines now handle the boolean 'weighted_average' to switch to unweighted mean, similar to legacy methods
+
 - Implementation of pilx (pyFAI-diffmap-view command): interactive viewer for pyFAI-diffmap files (thanks Loic Huder)
 - Creation of a RingExtraction class based on multi-threading (thanks Emily Massahud)
 - Flat-field and dark current corrections for pyFAI-calib2
@@ -217,18 +221,18 @@ Change-log of versions
 - Facts and figures:
     + 400+ commits, 100 PR
     +with the contribution of:
-        Clemens Prescher,
-        Elena Pascal,
-        Jérôme Kieffer,
-        Malte Storm,
-        Marco Cammarata,
-        Michael Hudson-Doyle,
-        Picca Frédéric-Emmanuel,
-        Rodrigo Telles,
-        Thomas A Caswell,
-        Tommaso Vinci,
-        Valentin Valls,
-        Wout de Nolf.
+        - Clemens Prescher,
+        - Elena Pascal,
+        - Jérôme Kieffer,
+        - Malte Storm,
+        - Marco Cammarata,
+        - Michael Hudson-Doyle,
+        - Picca Frédéric-Emmanuel,
+        - Rodrigo Telles,
+        - Thomas A Caswell,
+        - Tommaso Vinci,
+        - Valentin Valls,
+        - Wout de Nolf.
 
 0.21.3 24/03/2022
 -----------------

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -13,6 +13,7 @@
 
 import sys
 import os
+import pydata_sphinx_theme
 
 on_rtd = os.environ.get('READTHEDOCS') == 'True'
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -70,18 +71,12 @@
     'sphinxcontrib.programoutput',
     'sphinx.ext.mathjax',
     'nbsphinx',
+    'pydata_sphinx_theme',
 ]
 
 if sphinx.__version__ < "1.4":
     extensions.append('sphinx.ext.pngmath')
 
-# Set the theme to sphinx_rtd_theme when *not* building on Read The Docs.
-# The theme is set to default otherwise as Read The Docs uses its own theme anyway.
-if not on_rtd:
-    import sphinx_rtd_theme
-
-    extensions.append('sphinx_rtd_theme')
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -145,15 +140,36 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default' if on_rtd else 'sphinx_rtd_theme'
+html_theme = "pydata_sphinx_theme"
 
 # 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 = {}
-
+html_theme_options = {}
+# html_theme_options = {
+#     "icon_links": [
+#         {
+#             "name": "GitHub",
+#             "url": "https://github.com/silx-kit/pyFAI",
+#             "icon": "fa-brands fa-github",
+#         },
+#         {
+#             "name": "PyPI",
+#             "url": "https://pypi.org/project/pyFAI",
+#             "icon": "img/pypi.svg",
+#             "type": "local",
+#         },
+#     ],
+#     "show_toc_level": 1,
+#     "navbar_align": "left",
+#     "show_version_warning_banner": True,
+#     "navbar_start": ["navbar-logo", "version"],
+#     "navbar_center": ["navbar-nav"],
+#     "footer_start": ["copyright"],
+#     "footer_center": ["sphinx-version"],
+# }
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
+#html_theme_path = [pydata_sphinx_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -174,7 +190,7 @@
 # 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 = []
+html_static_path = ["img"]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

diff --git a/doc/source/conventions.rst b/doc/source/conventions.rst
@@ -36,7 +36,6 @@ Detector orientation
 
 Since 2023.12, it is possible to take into account the detector orientation in pyFAI.
 There is a norme in photography for storing this kind of information in an EXIF tag as an integer with a value from 1 to 8::
-
     1        2       3       4         5            6           7          8
  o              o                 o                                              o
   888888  888888      88   88      8888888888  88                  88  8888888888
@@ -45,6 +44,7 @@ There is a norme in photography for storing this kind of information in an EXIF
   88          88      88   88                 o                      o
   88          88  888888   888888
                         o o
+
 In photography the observer is behind the camera, thus the image's first pixel of the image (origin, noted (o)) is by default on the top-left.
 This differes in two point with pyFAI's definition: