🔧 Add tests for documentation

* Fix syntax in a code-block
veit · May 2, 2024 · 4891f10 · 4891f10
1 parent 996667e
commit 4891f10
Show file tree

Hide file tree

Showing 10 changed files with 112 additions and 94 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,31 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v3
+    - uses: actions/cache@v3
+      with:
+        path: ~/.cache/pre-commit
+        key: pre-commit|${{ env.pythonLocation }}|${{ hashFiles('.pre-commit-config.yaml') }}
+    - uses: pre-commit/action@v3.0.1
+
+  docs:
+    name: Build docs and run doctests
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        cache: pip
+        # Keep in sync with .readthedocs.yaml
+        python-version: 3.12
+    - run: python -m sphinx -nb html docs/ docs/_build/html
+    - run: python -m sphinx -b linkcheck docs/ docs/_build/html
diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -24,6 +24,13 @@ repos:
   - repo: https://github.com/sphinx-contrib/sphinx-lint
     rev: v0.9.1
     hooks:
-      - id: sphinx-lint
-        args: [--jobs=1]
-        types: [rst]
+    - id: sphinx-lint
+      args: [--jobs=1]
+      types: [rst]
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: "v1.12.1"
+    hooks:
+    - id: blacken-docs
+      args: [--line-length=79]
+      additional_dependencies:
+      - black
diff --git a/docs/document/docstrings.rst b/docs/document/docstrings.rst
@@ -21,10 +21,7 @@ Sphinx-Konfigurationsdatei ``docs/conf.py`` angegeben:
 
 .. code-block:: python
 
-    extensions = [
-        'sphinx.ext.autodoc',
-        ...
-    ]
+    extensions = ["sphinx.ext.autodoc", ...]
 
 Wenn euer Paket und die zugehörige Dokumentation Teil desselben Repositorys
 sind, werden sie immer dieselbe relative Position im Dateisystem haben. In
@@ -33,7 +30,7 @@ bearbeiten, um den relativen Pfad zum Paket anzugeben, also:
 
 .. code-block:: python
 
-    sys.path.insert(0, os.path.abspath('..'))
+    sys.path.insert(0, os.path.abspath(".."))
     import requests
 
 Wenn ihr eure Sphinx-Dokumentation in einer virtuellen Umgebung installiert

diff --git a/docs/document/extensions.rst b/docs/document/extensions.rst
@@ -107,12 +107,10 @@ aussehen:
 
     import sys
     import os
-    sys.path.insert(0, os.path.abspath('exts'))
 
-    extensions = [
-        'foo',
-        ...
-        ]
+    sys.path.insert(0, os.path.abspath("exts"))
+
+    extensions = ["foo", ...]
 
 .. seealso::
     * `Developing extensions for Sphinx

diff --git a/docs/document/uml/index.rst b/docs/document/uml/index.rst
@@ -1,57 +1,54 @@
-Unified Modeling Language (UML)
-===============================
-
-Installation
-------------
-
-#. Installiert `plantuml <https://plantuml.com/starting>`_:
-
-   .. tab:: Linux
-
-       .. code-block:: console
-
-         $ sudo apt install plantuml
-
-   .. tab:: macOS
-
-      .. code-block:: console
-
-         $ brew install plantuml
-
-#. Installiert `sphinxcontrib-plantuml
-   <https://pypi.org/project/sphinxcontrib-plantuml/>`_:
-
-   .. tab:: Linux/macOS
-
-      .. code-block:: console
-
-         $ bin/python -m pip install sphinxcontrib-plantuml
-
-   .. tab:: Windows
-
-      .. code-block:: ps1con
-
-         C:> Scripts\python -m pip install sphinxcontrib-plantuml
-
-#. Konfiguriert Sphinx in der ``conf.py``-Datei:
-
-   .. code-block:: python
-
-      extensions = [
-         ...,
-         'sphinxcontrib.plantuml',
-         ]
-
-      plantuml = '/PATH/TO/PLANTUML'
-
-   .. note::
-      Auch in Windows werden in der Pfadangabe ``/`` angegeben.
-
-.. toctree::
-   :titlesonly:
-   :hidden:
-
-   sequence-diagram
-   use-case-diagram
-   activity-diagram
-   class-diagram
+Unified Modeling Language (UML)
+===============================
+
+Installation
+------------
+
+#. Installiert `plantuml <https://plantuml.com/starting>`_:
+
+   .. tab:: Linux
+
+       .. code-block:: console
+
+         $ sudo apt install plantuml
+
+   .. tab:: macOS
+
+      .. code-block:: console
+
+         $ brew install plantuml
+
+#. Installiert `sphinxcontrib-plantuml
+   <https://pypi.org/project/sphinxcontrib-plantuml/>`_:
+
+   .. tab:: Linux/macOS
+
+      .. code-block:: console
+
+         $ bin/python -m pip install sphinxcontrib-plantuml
+
+   .. tab:: Windows
+
+      .. code-block:: ps1con
+
+         C:> Scripts\python -m pip install sphinxcontrib-plantuml
+
+#. Konfiguriert Sphinx in der ``conf.py``-Datei:
+
+   .. code-block:: python
+
+      extensions = [..., "sphinxcontrib.plantuml"]
+
+      plantuml = "/PATH/TO/PLANTUML"
+
+   .. note::
+      Auch in Windows werden in der Pfadangabe ``/`` angegeben.
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   sequence-diagram
+   use-case-diagram
+   activity-diagram
+   class-diagram
diff --git a/docs/test/coverage.rst b/docs/test/coverage.rst
@@ -218,7 +218,7 @@ enthalten, der so oder so ähnlich aussieht:
 
 .. code-block:: python
 
-    if __name__ == '__main__':
+    if __name__ == "__main__":
         main()
 
 Dieser Befehl weist Python an, :func:`main()` auszuführen, wenn wir das Modul
@@ -228,7 +228,7 @@ einer einfachen Pragma-Anweisung vom Testen ausgeschlossen:
 
 .. code-block:: python
 
-    if __name__ == '__main__': # pragma: no cover
+    if __name__ == "__main__":  # pragma: no cover
         main()
 
 Damit wird Coverage.py angewiesen, entweder eine einzelne Zeile oder einen

diff --git a/docs/test/pytest/fixtures.rst b/docs/test/pytest/fixtures.rst
@@ -753,6 +753,8 @@ einem Namensparameter an ``@pytest.fixture()``:
 
 
     from items import cli
+
+
     @pytest.fixture(scope="session", name="db")
     def _db():
         """The db object"""

diff --git a/docs/test/pytest/params.rst b/docs/test/pytest/params.rst
@@ -51,14 +51,18 @@ oder sogar schon "done" sein. Lasst uns alle drei testen:
 
 
     def test_finish_from_in_prog(items_db):
-        index = items_db.add_item(Item("Update pytest section", state="in progress"))
+        index = items_db.add_item(
+            Item("Update pytest section", state="in progress")
+        )
         items_db.finish(index)
         item = items_db.get_item(index)
         assert item.state == "done"
 
 
     def test_finish_from_done(items_db):
-        index = items_db.add_item(Item("Update cibuildwheel section", state="done"))
+        index = items_db.add_item(
+            Item("Update cibuildwheel section", state="done")
+        )
         items_db.finish(index)
         item = items_db.get_item(index)
         assert item.state == "done"

diff --git a/docs/test/unittest2.rst b/docs/test/unittest2.rst
@@ -16,8 +16,8 @@ vereinfachen:
 
     import unittest2 as unittest
 
-    class MyTest(unittest.TestCase):
-        ...
+
+    class MyTest(unittest.TestCase): ...
 
 Auf diese Weise könnt ihr, wenn ihr zu einer neueren Python-Version wechselt und
 das Modul ``unittest2`` nicht mehr benötigt, einfach den Import in eurem