Docs: Fix Build & HTML5

Fix RTD build and HTML5 issues in rendering. Add a few Sphinx warnings (duplicate labels, ill-formed commands, outdated configs, etc.) on the way.
ComputationalRadiationPhysics · Jun 15, 2023 · 8754d97 · 8754d97
1 parent 7420967
commit 8754d97
Show file tree

Hide file tree

Showing 8 changed files with 72 additions and 77 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,16 +1,20 @@
 version: 2
+
 build:
-    os: ubuntu-20.04
-    tools:
-        python: "3.9"
-    apt_packages:
-      - graphviz
-
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  apt_packages:
+  - graphviz
+
+sphinx:
+ configuration: docs/source/conf.py
+
 python:
-   install:
-   - requirements: docs/requirements.txt
+ install:
+ - requirements: docs/requirements.txt
 
 formats:
-    - htmlzip
-    - pdf
-    - epub
+  - htmlzip
+  - pdf
+  - epub
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,19 +1,14 @@
-# restrict up to the next major as suggested in the rtd documentation
-sphinx_rtd_theme<=2.0.0
-# recommonmark was discontinued myst-parser is the new replacement
+breathe
+docutils
+markupsafe
 myst-parser
-# rtd theme supports at least up to 4.1 but newest autoapi requires >=5.2 and myst-parser needs >=5
-sphinx==5.2.0
-breathe>=4.12.0
+pygments
+sphinx>=5.3
 sphinxcontrib.programoutput
 sphinxcontrib-napoleon>=0.7
 sphinx-autoapi
-pygments
-# restrict up to next major
-Jinja2<4.0
-markupsafe<3.0.0
-# rtd theme supports up to 0.17
-docutils<=0.17
+sphinx_rtd_theme>=1.1.1
+typeguard
 # generate plots
 matplotlib
 scipy

diff --git a/docs/source/_static/hide_chapter_titles.css b/docs/source/_static/hide_chapter_titles.css
@@ -1,24 +1,24 @@
 /* front page: hide chapter titles
  * needed for consistent HTML-PDF-EPUB chapters
  */
-#how-to-read-this-document.section div.section {
-    display:none;
+section#how-to-read-this-document div.section {
+    display: block;
 }
 
 /* parameter files: only show short intro of title
  * and description in HTML.
  * Work-Around for https://github.com/michaeljones/breathe/issues/318
  */
-div#pic-core.section > div > dl.type,
-div#pic-core.section > div > div.breathe-sectiondef,
-div#memory.section > div > dl.type,
-div#memory.section > div > div.breathe-sectiondef,
-div#pic-extensions.section > div > dl.type,
-div#pic-extensions.section > div > div.breathe-sectiondef,
-div#plugins.section > div > dl.type,
-div#plugins.section > div > div.breathe-sectiondef,
-div#misc.section > div > dl.type,
-div#misc.section > div > div.breathe-sectiondef
+section#pic-core dl.type,
+section#pic-core div.breathe-sectiondef,
+section#memory dl.type,
+section#memory div.breathe-sectiondef,
+section#pic-extensions dl.type,
+section#pic-extensions div.breathe-sectiondef,
+section#plugins dl.type,
+section#plugins div.breathe-sectiondef,
+section#misc dl.type,
+section#misc div.breathe-sectiondef
 {
     display: none;
 }

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -124,7 +124,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/docs/source/install/profile.rst b/docs/source/install/profile.rst
@@ -62,9 +62,9 @@ and providing default parameters for :ref:`TBG <usage-tbg>`.
 Crusher (ORNL)
 --------------
 
-**System overview:** `link <https://docs.olcf.ornl.gov/systems/crusher_quick_start_guide.html#system-overview>`_
+**System overview:** `link <https://docs.olcf.ornl.gov/systems/crusher_quick_start_guide.html#system-overview>`__
 
-**Production directory:** usually ``$PROJWORK/$proj/`` (`link <https://docs.olcf.ornl.gov/systems/crusher_quick_start_guide.html#data-and-storage>`_).
+**Production directory:** usually ``$PROJWORK/$proj/`` (`link <https://docs.olcf.ornl.gov/systems/crusher_quick_start_guide.html#data-and-storage>`__).
 Note that ``$HOME`` is mounted on compute nodes as read-only.
 
 For this profile to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>` and install :ref:`PNGwriter and openPMD <install-dependencies>` manually.
@@ -84,7 +84,7 @@ MI250X GPUs using craycc
 Hemera (HZDR)
 -------------
 
-**System overview:** `link (internal) <https://www.hzdr.de/db/Cms?pOid=29813>`_
+**System overview:** `link (internal) <https://www.hzdr.de/db/Cms?pOid=29813>`__
 
 **User guide:** *None*
 
@@ -132,11 +132,11 @@ Queue: k80 (8x NVIDIA K80 12GB)
 Summit (ORNL)
 -------------
 
-**System overview:** `link <https://www.olcf.ornl.gov/olcf-resources/compute-systems/summit/>`_
+**System overview:** `link <https://www.olcf.ornl.gov/olcf-resources/compute-systems/summit/>`__
 
-**User guide:** `link <https://www.olcf.ornl.gov/for-users/system-user-guides/summit/>`_
+**User guide:** `link <https://www.olcf.ornl.gov/for-users/system-user-guides/summit/>`__
 
-**Production directory:** usually ``$PROJWORK/$proj/`` (`link <https://www.olcf.ornl.gov/for-users/system-user-guides/summit/summit-user-guide/#file-systems>`_).
+**Production directory:** usually ``$PROJWORK/$proj/`` (`link <https://www.olcf.ornl.gov/for-users/system-user-guides/summit/summit-user-guide/#file-systems>`__).
 Note that ``$HOME`` is mounted on compute nodes as read-only.
 
 For this profile to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>` and install :ref:`PNGwriter <install-dependencies>` manually.
@@ -150,11 +150,11 @@ V100 GPUs (recommended)
 Piz Daint (CSCS)
 ----------------
 
-**System overview:** `link <https://www.cscs.ch/computers/piz-daint/>`_
+**System overview:** `link <https://www.cscs.ch/computers/piz-daint/>`__
 
-**User guide:** `link <https://user.cscs.ch/>`_
+**User guide:** `link <https://user.cscs.ch/>`__
 
-**Production directory:** ``$SCRATCH`` (`link <https://user.cscs.ch/storage/file_systems/>`_).
+**Production directory:** ``$SCRATCH`` (`link <https://user.cscs.ch/storage/file_systems/>`__).
 
 For this profile to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>` and install :ref:`boost, libpng, PNGwriter and ADIOS2 <install-dependencies>` manually.
 
@@ -173,9 +173,9 @@ For this profile to work, you need to download the :ref:`PIConGPU source code <i
 Taurus (TU Dresden)
 -------------------
 
-**System overview:** `link <https://tu-dresden.de/zih/hochleistungsrechnen/hpc>`_
+**System overview:** `link <https://tu-dresden.de/zih/hochleistungsrechnen/hpc>`__
 
-**User guide:** `link <https://doc.zih.tu-dresden.de/hpc-wiki/bin/view/Compendium/SystemTaurus>`_
+**User guide:** `link <https://doc.zih.tu-dresden.de/hpc-wiki/bin/view/Compendium/SystemTaurus>`__
 
 **Production directory:** ``/scratch/$USER/`` and ``/scratch/$proj/``
 
@@ -207,11 +207,11 @@ For this profile, you additionally need to compile and install everything for th
 Cori (NERSC)
 ------------
 
-**System overview:** `link <https://www.nersc.gov/users/computational-systems/cori/configuration/>`_
+**System overview:** `link <https://www.nersc.gov/users/computational-systems/cori/configuration/>`__
 
-**User guide:** `link <https://docs.nersc.gov/>`_
+**User guide:** `link <https://docs.nersc.gov/>`__
 
-**Production directory:** ``$SCRATCH`` (`link <https://www.nersc.gov/users/storage-and-file-systems/>`_).
+**Production directory:** ``$SCRATCH`` (`link <https://www.nersc.gov/users/storage-and-file-systems/>`__).
 
 For these profiles to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>` and install :ref:`PNGwriter <install-dependencies>` manually.
 
@@ -224,9 +224,9 @@ Queue: dgx (DGX - A100)
 Draco (MPCDF)
 -------------
 
-**System overview:** `link <https://www.mpcdf.mpg.de/services/computing/draco/about-the-system>`_
+**System overview:** `link <https://www.mpcdf.mpg.de/services/computing/draco/about-the-system>`__
 
-**User guide:** `link <https://www.mpcdf.mpg.de/services/computing/draco>`_
+**User guide:** `link <https://www.mpcdf.mpg.de/services/computing/draco>`__
 
 **Production directory:** ``/ptmp/$USER/``
 
@@ -238,11 +238,11 @@ For this profile to work, you need to download the :ref:`PIConGPU source code <i
 D.A.V.I.D.E (CINECA)
 --------------------
 
-**System overview:** `link <http://www.hpc.cineca.it/content/davide>`_
+**System overview:** `link <http://www.hpc.cineca.it/content/davide>`__
 
-**User guide:** `link <https://wiki.u-gov.it/confluence/display/SCAIUS/UG3.2%3A+D.A.V.I.D.E.+UserGuide>`_
+**User guide:** `link <https://wiki.u-gov.it/confluence/display/SCAIUS/UG3.2%3A+D.A.V.I.D.E.+UserGuide>`__
 
-**Production directory:** ``$CINECA_SCRATCH/`` (`link <https://wiki.u-gov.it/confluence/display/SCAIUS/UG2.4%3A+Data+storage+and+FileSystems>`_)
+**Production directory:** ``$CINECA_SCRATCH/`` (`link <https://wiki.u-gov.it/confluence/display/SCAIUS/UG2.4%3A+Data+storage+and+FileSystems>`__)
 
 For this profile to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>` manually.
 
@@ -255,11 +255,11 @@ Queue: dvd_usr_prod (Nvidia P100 GPUs)
 JURECA (JSC)
 ------------
 
-**System overview:** `link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JURECA/JURECA_node.html>`_
+**System overview:** `link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JURECA/JURECA_node.html>`__
 
-**User guide:** `link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JURECA/UserInfo/UserInfo_node.html>`_
+**User guide:** `link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JURECA/UserInfo/UserInfo_node.html>`__
 
-**Production directory:** ``$SCRATCH`` (`link <http://www.fz-juelich.de/SharedDocs/FAQs/IAS/JSC/EN/JUST/FAQ_00_File_systems.html?nn=1297148>`_)
+**Production directory:** ``$SCRATCH`` (`link <http://www.fz-juelich.de/SharedDocs/FAQs/IAS/JSC/EN/JUST/FAQ_00_File_systems.html?nn=1297148>`__)
 
 For these profiles to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>` and install :ref:`PNGwriter and openPMD <install-dependencies>`, for the gpus partition also :ref:`Boost and HDF5 <install-dependencies>`, manually.
 
@@ -284,11 +284,11 @@ Queue: booster (Intel Xeon Phi 7250-F, 68 cores + Hyperthreads)
 JUWELS (JSC)
 ------------
 
-**System overview:** `link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JUWELS/JUWELS_node.html>`_
+**System overview:** `link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JUWELS/JUWELS_node.html>`__
 
-**User guide:** `link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JUWELS/UserInfo/UserInfo_node.html>`_
+**User guide:** `link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JUWELS/UserInfo/UserInfo_node.html>`__
 
-**Production directory:** ``$SCRATCH`` (`link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JUWELS/FAQ/juwels_FAQ_node.html#faq1495160>`_)
+**Production directory:** ``$SCRATCH`` (`link <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JUWELS/FAQ/juwels_FAQ_node.html#faq1495160>`__)
 
 For these profiles to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>` and install :ref:`PNGwriter and openPMD <install-dependencies>`, for the gpus partition also :ref:`Boost and HDF5 <install-dependencies>`, manually.
 
@@ -307,11 +307,11 @@ Queue: gpus (4 x Nvidia V100 GPUs)
 ARIS (GRNET)
 ------------
 
-**System overview:** `link <http://doc.aris.grnet.gr/>`_
+**System overview:** `link <http://doc.aris.grnet.gr/>`__
 
-**User guide:** `link <http://doc.aris.grnet.gr/environment/>`_
+**User guide:** `link <http://doc.aris.grnet.gr/environment/>`__
 
-**Production directory:** ``$WORKDIR`` (`link <http://doc.aris.grnet.gr/system/storage/>`_)
+**Production directory:** ``$WORKDIR`` (`link <http://doc.aris.grnet.gr/system/storage/>`__)
 
 For these profiles to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>`.
 
@@ -324,9 +324,9 @@ Queue: gpu (2 x NVIDIA Tesla k40m GPUs)
 Ascent (ORNL)
 -------------
 
-**System overview and user guide:** `link <https://docs.olcf.ornl.gov/systems/ascent_user_guide.html#system-overview/>`_
+**System overview and user guide:** `link <https://docs.olcf.ornl.gov/systems/ascent_user_guide.html#system-overview/>`__
 
-**Production directory:** usually ``$PROJWORK/$proj/`` (as on summit `link <https://www.olcf.ornl.gov/for-users/system-user-guides/summit/summit-user-guide/#file-systems>`_).
+**Production directory:** usually ``$PROJWORK/$proj/`` (as on summit `link <https://www.olcf.ornl.gov/for-users/system-user-guides/summit/summit-user-guide/#file-systems>`__).
 
 For this profile to work, you need to download the :ref:`PIConGPU source code <install-dependencies-picongpu>` and install :ref:`openPMD-api and PNGwriter <install-dependencies>` manually or use pre-installed libraries in the shared project directory.
 
@@ -335,9 +335,3 @@ V100 GPUs (recommended)
 
 .. literalinclude:: profiles/ascent-ornl/gpu_picongpu.profile.example
    :language: bash
-
-Queue: gpu (8 x NVIDIA Tesla k10 GPUs)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. literalinclude:: profiles/dicc-um/gpu_picongpu.profile.example
-   :language: bash
diff --git a/docs/source/testing/testbuilding.rst b/docs/source/testing/testbuilding.rst
@@ -1,7 +1,7 @@
-.. _testing-usage:
+.. _testing-new:
 
 How to setup a new test
-======================
+=======================
 
 General
 -------

diff --git a/docs/source/usage/plugins/openPMD.rst b/docs/source/usage/plugins/openPMD.rst
@@ -105,7 +105,7 @@ The extended format is only available for configuration of the writing procedure
 The reading procedures (i.e. for restarting from a checkpoint) can be configured via ``--checkpoint.openPMD.jsonRestart``, e.g. see the example below for configuring the number of blosc decompression threads in ADIOS2.
 Note that most sensible use cases for this command line option (including this example) require openPMD-api >= 0.15 (or a recent dev version until the 0.15 release).
 
-.. literatlinclude:: openPMD_restart_config.json
+.. literalinclude:: openPMD_restart_config.json
 
 Two data preparation strategies are available for downloading particle data off compute devices.
 

diff --git a/share/picongpu/examples/atomicPhysics/README.rst b/share/picongpu/examples/atomicPhysics/README.rst
@@ -3,14 +3,16 @@ atomicPhysics: atomic Physics example for experimental FLYonPIC PIConGPU extensi
 ============================
 
 .. sectionauthor:: Brian Marre <b.marre (at) hzdr.de>
+
 This is a minimum spec-exmaple for testing the still experimental atomic physics branch of
 picongpu.
 It uses mostly default picongpu algorithms and settings, except for a few
 changes listed below, to reduce computation time.
+
  - reduced super cell size, only 2x2x2 cells form a super cell
  - reduced number of particels overall, only 1 macro-ion and 1 macro-electron per super cell
  - no ionization, instead initialization in a somewhat correct charge state for initial
-    conidtions
+   conditions
 
 Use this as a starting point for your own atomic physics picongpu simulations, but beware
-this is still experimental
+this is still experimental.