📝 Rearrange documentation tests

veit · Sep 7, 2024 · 4befd2e · 4befd2e
1 parent cba8935
commit 4befd2e
Showing 1 changed file with 134 additions and 131 deletions.
diff --git a/docs/document/test.rst b/docs/document/test.rst
@@ -1,8 +1,140 @@
 Testing
 =======
 
-Formatting
-----------
+Builds and links
+----------------
+
+.. _build-errors:
+
+Build errors
+~~~~~~~~~~~~
+
+You have the option of checking whether your content is built correctly before
+publishing your changes. `Sphinx <https://www.sphinx-doc.org/>`_ has a nitpicky
+mode for this, which can be called up with the ``-n`` option, for example with:
+
+.. tab:: Linux/macOS
+
+   .. code-block:: console
+
+       $ bin/python -m sphinx -nb html docs/ docs/_build/
+
+.. tab:: Windows
+
+   .. code-block:: ps1con
+
+       C:> Scripts\python -m sphinx -nb html docs\ docs\_build\
+
+.. _link-checks:
+
+links
+~~~~~
+
+You can also automatically ensure that the link targets you specify are
+accessible. Our documentation tool Sphinx uses a ``linkcheck`` builder for this,
+which you can call up with:
+
+.. tab:: Linux/macOS
+
+   .. code-block:: console
+
+       $ bin/python -m sphinx -b linkcheck docs/ docs/_build/
+
+.. tab:: Windows
+
+   .. code-block:: ps1con
+
+       C:> Scripts\python -m sphinx -b linkcheck docs\ docs\_build\
+
+The output can then look like this, for example:
+
+.. tab:: Linux/macOS
+
+   .. code-block:: console
+
+       $ bin/python -m sphinx -b linkcheck docs/ docs/_build/
+       Running Sphinx v3.5.2
+       loading translations [de]... done
+       …
+       building [mo]: targets for 0 po files that are out of date
+       building [linkcheck]: targets for 27 source files that are out of date
+       …
+       (content/accessibility: line   89) ok        https://bbc.github.io/subtitle-guidelines/
+       (content/writing-style: line  164) ok        http://disabilityinkidlit.com/2016/07/08/introduction-to-disability-terminology/
+
+       …
+       (   index: line    5) redirect  https://cusy-design-system.readthedocs.io/ - with Found to https://cusy-design-system.readthedocs.io/de/latest/
+       …
+       (accessibility/color: line  114) broken    https://chrome.google.com/webstore/detail/nocoffee/jjeeggmbnhckmgdhmgdckeigabjfbddl - 404 Client Error: Not Found for url: https://chrome.google.com/webstore/detail/nocoffee/jjeeggmbnhckmgdhmgdckeigabjfbddl
+
+.. tab:: Windows
+
+   .. code-block:: ps1con
+
+       C:> Scripts\python -m sphinx -b linkcheck docs\ docs\_build\
+       Running Sphinx v3.5.2
+       loading translations [de]... done
+       …
+       building [mo]: targets for 0 po files that are out of date
+       building [linkcheck]: targets for 27 source files that are out of date
+       …
+       (content/accessibility: line   89) ok        https://bbc.github.io/subtitle-guidelines/
+       (content/writing-style: line  164) ok        http://disabilityinkidlit.com/2016/07/08/introduction-to-disability-terminology/
+
+       …
+       (   index: line    5) redirect  https://cusy-design-system.readthedocs.io/ - with Found to https://cusy-design-system.readthedocs.io/de/latest/
+       …
+       (accessibility/color: line  114) broken    https://chrome.google.com/webstore/detail/nocoffee/jjeeggmbnhckmgdhmgdckeigabjfbddl - 404 Client Error: Not Found for url: https://chrome.google.com/webstore/detail/nocoffee/jjeeggmbnhckmgdhmgdckeigabjfbddl
+
+Continuous integration
+~~~~~~~~~~~~~~~~~~~~~~
+
+If necessary, you can also check automatically in your :term:`CI` pipeline
+whether the documentation is being built and the links are valid. In
+:doc:`../test/tox`, the configuration can be added as follows:
+
+.. code-block:: ini
+   :caption: tox.ini
+
+   [testenv:docs]
+   # Keep base_python in sync with ci.yml and .readthedocs.yaml.
+   base_python = py312
+   extras = docs
+   commands =
+     sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
+
+   [testenv:docs-linkcheck]
+   base_python = {[testenv:docs]base_python}
+   extras = {[testenv:docs]extras}
+   commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html
+
+You can then define the following jobs for GitHub, for example:
+
+.. code-block:: yaml
+   :caption: .github/workflows/ci.yml
+
+   docs:
+     name: Build docs and run doctests
+     needs: build-package
+     runs-on: ubuntu-latest
+     steps:
+     - name: Download pre-built packages
+       uses: actions/download-artifact@v4
+       with:
+         name: Packages
+         path: dist
+     - run: tar xf dist/*.tar.gz --strip-components=1
+
+     - uses: actions/setup-python@v5
+       with:
+         # Keep in sync with tox.ini/docs and .readthedocs.yaml
+         python-version: "3.12"
+         cache: pip
+     - run: python -m pip install tox
+     - run: python -m tox run -e docs
+
+reST formatting
+---------------
 
 Whether the :doc:`Sphinx <start>` documentation is written in valid :doc:`rest`
 format can be checked with `sphinx-lint
@@ -230,132 +362,3 @@ You can also use ``interrogate`` with :doc:`pre-commit
          - id: interrogate
            args: [--quiet, --fail-under=95]
            pass_filenames: false
-
-.. _build-errors:
-
-Build errors
-------------
-
-You have the option of checking whether your content is built correctly before
-publishing your changes. `Sphinx <https://www.sphinx-doc.org/>`_ has a nitpicky
-mode for this, which can be called up with the ``-n`` option, for example with:
-
-.. tab:: Linux/macOS
-
-   .. code-block:: console
-
-       $ bin/python -m sphinx -nb html docs/ docs/_build/
-
-.. tab:: Windows
-
-   .. code-block:: ps1con
-
-       C:> Scripts\python -m sphinx -nb html docs\ docs\_build\
-
-.. _link-checks:
-
-Check links
------------
-
-You can also automatically ensure that the link targets you specify are
-accessible. Our documentation tool Sphinx uses a ``linkcheck`` builder for this,
-which you can call up with:
-
-.. tab:: Linux/macOS
-
-   .. code-block:: console
-
-       $ bin/python -m sphinx -b linkcheck docs/ docs/_build/
-
-.. tab:: Windows
-
-   .. code-block:: ps1con
-
-       C:> Scripts\python -m sphinx -b linkcheck docs\ docs\_build\
-
-The output can then look like this, for example:
-
-.. tab:: Linux/macOS
-
-   .. code-block:: console
-
-       $ bin/python -m sphinx -b linkcheck docs/ docs/_build/
-       Running Sphinx v3.5.2
-       loading translations [de]... done
-       …
-       building [mo]: targets for 0 po files that are out of date
-       building [linkcheck]: targets for 27 source files that are out of date
-       …
-       (content/accessibility: line   89) ok        https://bbc.github.io/subtitle-guidelines/
-       (content/writing-style: line  164) ok        http://disabilityinkidlit.com/2016/07/08/introduction-to-disability-terminology/
-
-       …
-       (   index: line    5) redirect  https://cusy-design-system.readthedocs.io/ - with Found to https://cusy-design-system.readthedocs.io/de/latest/
-       …
-       (accessibility/color: line  114) broken    https://chrome.google.com/webstore/detail/nocoffee/jjeeggmbnhckmgdhmgdckeigabjfbddl - 404 Client Error: Not Found for url: https://chrome.google.com/webstore/detail/nocoffee/jjeeggmbnhckmgdhmgdckeigabjfbddl
-
-.. tab:: Windows
-
-   .. code-block:: ps1con
-
-       C:> Scripts\python -m sphinx -b linkcheck docs\ docs\_build\
-       Running Sphinx v3.5.2
-       loading translations [de]... done
-       …
-       building [mo]: targets for 0 po files that are out of date
-       building [linkcheck]: targets for 27 source files that are out of date
-       …
-       (content/accessibility: line   89) ok        https://bbc.github.io/subtitle-guidelines/
-       (content/writing-style: line  164) ok        http://disabilityinkidlit.com/2016/07/08/introduction-to-disability-terminology/
-
-       …
-       (   index: line    5) redirect  https://cusy-design-system.readthedocs.io/ - with Found to https://cusy-design-system.readthedocs.io/de/latest/
-       …
-       (accessibility/color: line  114) broken    https://chrome.google.com/webstore/detail/nocoffee/jjeeggmbnhckmgdhmgdckeigabjfbddl - 404 Client Error: Not Found for url: https://chrome.google.com/webstore/detail/nocoffee/jjeeggmbnhckmgdhmgdckeigabjfbddl
-
-Continuous integration
-----------------------
-
-If necessary, you can also check automatically in your :term:`CI` pipeline
-whether the documentation is being built and the links are valid. In
-:doc:`../test/tox`, the configuration can be added as follows:
-
-.. code-block:: ini
-   :caption: tox.ini
-
-   [testenv:docs]
-   # Keep base_python in sync with ci.yml and .readthedocs.yaml.
-   base_python = py312
-   extras = docs
-   commands =
-     sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
-
-   [testenv:docs-linkcheck]
-   base_python = {[testenv:docs]base_python}
-   extras = {[testenv:docs]extras}
-   commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html
-
-You can then define the following jobs for GitHub, for example:
-
-.. code-block:: yaml
-   :caption: .github/workflows/ci.yml
-
-   docs:
-     name: Build docs and run doctests
-     needs: build-package
-     runs-on: ubuntu-latest
-     steps:
-     - name: Download pre-built packages
-       uses: actions/download-artifact@v4
-       with:
-         name: Packages
-         path: dist
-     - run: tar xf dist/*.tar.gz --strip-components=1
-
-     - uses: actions/setup-python@v5
-       with:
-         # Keep in sync with tox.ini/docs and .readthedocs.yaml
-         python-version: "3.12"
-         cache: pip
-     - run: python -m pip install tox
-     - run: python -m tox run -e docs