Merge pull request #187 from scipp/docs-fixes

Fix warnings and other issues in docs

Author: jl-wynen

docs/api-reference/index.md

@@ -10,6 +10,15 @@
    :toctree: ../generated/attributes
 
    providers
+
+.. autosummary::
+   :toctree: ../generated/classes
+
+   RunNormalization
+
+.. autosummary::
+   :toctree: ../generated/functions
+
    with_pixel_mask_filenames
 ```
 
@@ -21,17 +30,37 @@
    :template: module-template.rst
    :recursive:
 
+   calibration
    conversion
    correction
    filtering
    grouping
+   logging
+   masking
    smoothing
    transform
    types
 ```
 
 ## ESSdream
 
+### Workflows
+
+
+```{eval-rst}
+.. currentmodule:: ess.dream
+
+.. autosummary::
+   :toctree: ../generated/functions
+
+   DreamGeant4MonitorHistogramWorkflow
+   DreamGeant4MonitorIntegratedWorkflow
+   DreamGeant4ProtonChargeWorkflow
+   DreamGeant4Workflow
+   DreamPowderWorkflow
+   DreamWorkflow
+```
+
 ### Top-level functions
 
 ```{eval-rst}
@@ -41,7 +70,18 @@
    :toctree: ../generated/functions
 
    instrument_view
-   DreamGeant4Workflow
+   load_geant4_csv
+```
+
+### Top-level classes
+
+```{eval-rst}
+.. currentmodule:: ess.dream
+
+.. autosummary::
+   :toctree: ../generated/classes
+
+   InstrumentConfiguration
 ```
 
 ### Submodules
@@ -52,6 +92,7 @@
    :template: module-template.rst
    :recursive:
 
+   beamline
    data
    diagnostics
    io

docs/conf.py

@@ -32,6 +32,7 @@
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinxcontrib.autodoc_pydantic",
     "sphinxcontrib.bibtex",
     "nbsphinx",
     "myst_parser",
@@ -69,9 +70,17 @@
 }
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
+    "pydantic": ("https://docs.pydantic.dev/latest", None),
+    "python": ("https://docs.python.org/3", None),
+    # Scipp:
+    "essreduce": ("https://scipp.github.io/essreduce", None),
+    "plopp": ("https://scipp.github.io/plopp", None),
+    "sciline": ("https://scipp.github.io/sciline", None),
     "scipp": ("https://scipp.github.io/", None),
+    "scippneutron": ("https://scipp.github.io/scippneutron", None),
+    "scippnexus": ("https://scipp.github.io/scippnexus", None),
+    "tof": ("https://scipp.github.io/tof", None),
 }
 
 # autodocs includes everything, even irrelevant API internals. autosummary

docs/user-guide/dream/dream-advanced-powder-reduction.ipynb

@@ -42,7 +42,7 @@
     "The basic notebook sums over all detector voxels and produces a 1D curve.\n",
     "Here, we instead bin by scattering angle $2\\theta$.\n",
     "\n",
-    "First, define the same workflow as in the [basic example](./dream-powder-reduction.rst#create_and_configure_the_workfow):"
+    "First, define the same workflow as in the [basic example](./dream-powder-reduction.rst):"
    ]
   },
   {

requirements/base.txt

@@ -1,9 +1,9 @@
 # SHA1:81114073dd5e4b765405b54b3976f92d6a96439b
 #
-# This file is autogenerated by pip-compile-multi
+# This file was generated by pip-compile-multi.
 # To update, run:
 #
-#    pip-compile-multi
+#    requirements upgrade
 #
 annotated-types==0.7.0
     # via pydantic
@@ -35,13 +35,13 @@ exceptiongroup==1.3.0
     # via ipython
 executing==2.2.0
     # via stack-data
-fonttools==4.58.1
+fonttools==4.58.4
     # via matplotlib
 fsspec==2025.5.1
     # via dask
-graphviz==0.20.3
+graphviz==0.21
     # via -r base.in
-h5py==3.13.0
+h5py==3.14.0
     # via
     #   scippneutron
     #   scippnexus
@@ -102,9 +102,9 @@ partd==1.4.2
     # via dask
 pexpect==4.9.0
     # via ipython
-pillow==11.2.1
+pillow==11.3.0
     # via matplotlib
-plopp==25.5.0
+plopp==25.6.1
     # via
     #   -r base.in
     #   scippneutron
@@ -115,11 +115,11 @@ ptyprocess==0.7.0
     # via pexpect
 pure-eval==0.2.3
     # via stack-data
-pydantic==2.11.5
+pydantic==2.11.7
     # via scippneutron
 pydantic-core==2.33.2
     # via pydantic
-pygments==2.19.1
+pygments==2.19.2
     # via ipython
 pyparsing==3.2.3
     # via matplotlib
@@ -143,11 +143,11 @@ scipp==25.5.1
     #   scippneutron
     #   scippnexus
     #   tof
-scippneutron==25.5.0
+scippneutron==25.6.0
     # via
     #   -r base.in
     #   essreduce
-scippnexus==25.4.0
+scippnexus==25.6.0
     # via
     #   -r base.in
     #   essreduce
@@ -177,7 +177,7 @@ traitlets==5.14.3
     #   traittypes
 traittypes==0.2.1
     # via ipydatawidgets
-typing-extensions==4.13.2
+typing-extensions==4.14.0
     # via
     #   exceptiongroup
     #   ipython
@@ -191,5 +191,5 @@ wcwidth==0.2.13
     # via prompt-toolkit
 widgetsnbextension==4.0.14
     # via ipywidgets
-zipp==3.22.0
+zipp==3.23.0
     # via importlib-metadata

requirements/basetest.txt

@@ -1,11 +1,11 @@
 # SHA1:c4f3e9aaa3abd10fcdf497bea14415857f62cc89
 #
-# This file is autogenerated by pip-compile-multi
+# This file was generated by pip-compile-multi.
 # To update, run:
 #
-#    pip-compile-multi
+#    requirements upgrade
 #
-certifi==2025.4.26
+certifi==2025.6.15
     # via requests
 charset-normalizer==3.4.2
     # via requests
@@ -21,29 +21,31 @@ packaging==25.0
     # via
     #   pooch
     #   pytest
-pandas==2.2.3
+pandas==2.3.0
     # via -r basetest.in
 platformdirs==4.3.8
     # via pooch
 pluggy==1.6.0
     # via pytest
 pooch==1.8.2
     # via -r basetest.in
-pytest==8.3.5
+pygments==2.19.2
+    # via pytest
+pytest==8.4.1
     # via -r basetest.in
 python-dateutil==2.9.0.post0
     # via pandas
 pytz==2025.2
     # via pandas
-requests==2.32.3
+requests==2.32.4
     # via pooch
 six==1.17.0
     # via python-dateutil
 tomli==2.2.1
     # via pytest
-typing-extensions==4.13.2
+typing-extensions==4.14.0
     # via exceptiongroup
 tzdata==2025.2
     # via pandas
-urllib3==2.4.0
+urllib3==2.5.0
     # via requests

requirements/ci.txt

@@ -1,13 +1,13 @@
 # SHA1:6344d52635ea11dca331a3bc6eb1833c4c64d585
 #
-# This file is autogenerated by pip-compile-multi
+# This file was generated by pip-compile-multi.
 # To update, run:
 #
-#    pip-compile-multi
+#    requirements upgrade
 #
-cachetools==6.0.0
+cachetools==6.1.0
     # via tox
-certifi==2025.4.26
+certifi==2025.6.15
     # via requests
 chardet==5.2.0
     # via tox
@@ -40,19 +40,19 @@ pluggy==1.6.0
     # via tox
 pyproject-api==1.9.1
     # via tox
-requests==2.32.3
+requests==2.32.4
     # via -r ci.in
 smmap==5.0.2
     # via gitdb
 tomli==2.2.1
     # via
     #   pyproject-api
     #   tox
-tox==4.26.0
+tox==4.27.0
     # via -r ci.in
-typing-extensions==4.13.2
+typing-extensions==4.14.0
     # via tox
-urllib3==2.4.0
+urllib3==2.5.0
     # via requests
 virtualenv==20.31.2
     # via tox

requirements/dev.txt

@@ -1,9 +1,9 @@
 # SHA1:efd19a3a98c69fc3d6d6233ed855de7e4a208f74
 #
-# This file is autogenerated by pip-compile-multi
+# This file was generated by pip-compile-multi.
 # To update, run:
 #
-#    pip-compile-multi
+#    requirements upgrade
 #
 -r base.txt
 -r ci.txt
@@ -16,7 +16,7 @@ anyio==4.9.0
     # via
     #   httpx
     #   jupyter-server
-argon2-cffi==23.1.0
+argon2-cffi==25.1.0
     # via jupyter-server
 argon2-cffi-bindings==21.2.0
     # via argon2-cffi
@@ -65,21 +65,21 @@ jupyter-server==2.16.0
     #   notebook-shim
 jupyter-server-terminals==0.5.3
     # via jupyter-server
-jupyterlab==4.4.3
+jupyterlab==4.4.4
     # via -r dev.in
 jupyterlab-server==2.27.3
     # via jupyterlab
 notebook-shim==0.2.4
     # via jupyterlab
 overrides==7.7.0
     # via jupyter-server
-pip-compile-multi==3.1.0
+pip-compile-multi==3.2.1
     # via -r dev.in
 pip-tools==7.4.1
     # via pip-compile-multi
 plumbum==1.9.0
     # via copier
-prometheus-client==0.22.0
+prometheus-client==0.22.1
     # via jupyter-server
 pycparser==2.22
     # via cffi

requirements/docs.in

@@ -1,4 +1,5 @@
 -r base.in
+autodoc-pydantic
 ipykernel
 ipympl
 ipython!=8.7.0  # Breaks syntax highlighting in Jupyter code cells.