🔧 Add tests for documentation

* Fix reST syntax
* Fix syntax in a code-block
* Add linkcheck ignore and linkcheck exclude lists
* Update autodoc examples

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+    - uses: actions/cache@v4
+      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 pip install -r docs/requirements.txt
+    - run: python -m sphinx -nb html docs/ docs/_build/html
+    - run: python -m sphinx -b linkcheck docs/ docs/_build/html

.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

docs/appendix/encodings.rst

@@ -13,13 +13,13 @@ folgenden String-Konstanten, die alle in den ASCII-Zeichensatz fallen:
 .. code-block:: python
 
     # Some strings for ctype-style character classification
-    whitespace = ' \t\n\r\v\f'
-    ascii_lowercase = 'abcdefghijklmnopqrstuvwxyz'
-    ascii_uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+    whitespace = " \t\n\r\v\f"
+    ascii_lowercase = "abcdefghijklmnopqrstuvwxyz"
+    ascii_uppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
     ascii_letters = ascii_lowercase + ascii_uppercase
-    digits = '0123456789'
-    hexdigits = digits + 'abcdef' + 'ABCDEF'
-    octdigits = '01234567'
+    digits = "0123456789"
+    hexdigits = digits + "abcdef" + "ABCDEF"
+    octdigits = "01234567"
     punctuation = r"""!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~"""
     printable = digits + ascii_letters + punctuation + whitespace
 
@@ -28,7 +28,7 @@ sein. ``hexdigits`` und ``octdigits`` beziehen sich auf die
 Hexadezimal- :abbr:`bzw. (beziehungsweise)` Oktalwerte. Ihr könnt diese
 Konstanten für alltägliche String-Manipulation verwenden:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> import string
     >>> hepy = "Hello Pythonistas!"
@@ -80,7 +80,7 @@ nicht von vornherein mit einer Kodierung versehen sind.
 :meth:`python3:str.encode` und :meth:`python3:bytes.decode` sind die Methoden
 des Übergangs vom einen zum anderen:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> "schön".encode("utf-8")
     b'sch\xc3\xb6n'
@@ -102,9 +102,9 @@ zwei Bytes, ``c3`` und ``b6`` als Hexadezimalwerte.
 Mit :meth:`python3:bytes.fromhex` könnt ihr die Hexadezimalwerte in Bytes
 umwandeln:
 
-.. code-block:: python
+.. code-block:: pycon
 
-    >>> bytes.fromhex('c3 b6')
+    >>> bytes.fromhex("c3 b6")
     b'\xc3\xb6'
 
 UTF-16 und UTF-32
@@ -114,7 +114,7 @@ Der Unterschied zwischen diesen und UTF-8 ist in der Praxis erheblich. Im
 Folgenden möchte ich euch nur kurz an einem Beispiel zeigen, dass hier eine
 eine Round-Trip-Konvertierung einfach fehlschlagen kann:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> hepy = "Hello Pythonistas!"
     >>> hepy.encode("utf-8")
@@ -153,7 +153,7 @@ Die einzige Ausnahme könnte :func:`open() <python3:open>` sein, das
 plattformabhängig ist und daher vom Wert von
 :func:`python3:locale.getpreferredencoding` abhängt:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> import locale
     >>> locale.getpreferredencoding()

docs/conf.py

@@ -19,7 +19,7 @@
 #
 # import os
 # import sys
-# sys.path.insert(0, os.path.abspath('.'))
+# sys.path.insert(0, os.path.abspath("."))
 
 import os
 import re
@@ -28,10 +28,10 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+# needs_sphinx = "1.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom ones.
 extensions = [
     "pygments_pytest",
     "sphinx.ext.autodoc",
@@ -55,13 +55,19 @@
     "Sybil": ("https://sybil.readthedocs.io/en/latest/", None),
 }
 
+linkcheck_ignore = ["*/_sources/*.rst.txt"]
+linkcheck_exclude_documents = [
+    r"autodoc-examples",
+    r"reference",
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
+# source_suffix = [".rst", ".md"]
 source_suffix = ".rst"
 
 # The master toctree document.
@@ -113,7 +119,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 = ['_static']
+# html_static_path = ["_static"]
 html_static_path = ["_static"]
 
 html_logo = "_static/images/logo/logo.png"
@@ -129,17 +135,17 @@
 # -- Options for LaTeX output ------------------------------------------
 
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
+    # The paper size ("letterpaper" or "a4paper").
+    # "papersize": "letterpaper",
     #
-    # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
+    # The font size ("10pt", "11pt" or "12pt").
+    # "pointsize": "10pt",
     #
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    # "preamble": "",
     #
     # Latex figure (float) alignment
-    # 'figure_align': 'htbp',
+    # "figure_align": "htbp",
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

docs/control-flows/boolean.rst

@@ -15,7 +15,7 @@ Konstante ``True`` und alles andere wird als ``True`` betrachtet.
     sind logischen Operatoren, mit denen die oben genannten Überprüfungen
     verknüpft werden können.
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> x = 3
    >>> y = 3.0
@@ -41,7 +41,7 @@ an zwei Stellen auf dasselbe Objekt verweisen.
 Am häufigsten werden ``is`` und ``is not`` in Verbindung mit
 :doc:`../types/none` verwendet:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> x is None
     False
@@ -54,7 +54,7 @@ None`` verwenden, sondern stattdessen ``x is None`` eingeben.
 
 Ihr solltet jedoch nie berechnete Fließkommazahlen miteinander vergleichen:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> u = 0.6 * 7
     >>> v = 0.7 * 6

docs/control-flows/if-elif-else.rst

@@ -5,7 +5,7 @@ Der Codeblock nach der ersten wahren Bedingung einer ``if``- oder
 ``elif``-Anweisung wird ausgeführt. Wenn keine der Bedingungen wahr ist, wird
 der Codeblock nach dem ``else`` ausgeführt:
 
-.. code-block:: python
+.. code-block:: pycon
     :linenos:
 
     >>> x = 1

docs/control-flows/loops.rst

@@ -7,7 +7,7 @@ Schleifen
 Die ``while``-Schleife wird so lange ausgeführt, wie die Bedingung (hier: ``x >
 y``) wahr ist:
 
-.. code-block:: python
+.. code-block:: pycon
     :linenos:
 
     >>> x, y = 6, 3
@@ -35,7 +35,7 @@ Zeilen 8 und 9
     gibt die Ergebnisse der ``while``-Schleife aus bevor die Ausführung mit
     ``break`` unterbrochen wurde.
 
-.. code-block:: python
+.. code-block:: pycon
     :linenos:
 
     >>> x, y = 6, 3
@@ -65,7 +65,7 @@ Element in einer Sequenz (:abbr:`z.B. (zum Beispiel)` eine :doc:`Liste
 <https://de.wikipedia.org/wiki/Division_mit_Rest#Modulo>`_-Operator ``%`` als
 Bedingung für as erste Vorkommen einer ganzen Zahl, die durch ``5`` teilbar ist:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> items = [1, "fünf", 5.0, 10, 11, 15]
     >>> d = 5
@@ -90,7 +90,7 @@ Schleifen mit einem Index
 Ihr könnt in einer ``for``-Schleife auch den Index ausgeben, :abbr:`z.B. (zum
 Beispiel)` mit :py:func:`enumerate`:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> data_types = ["Data types", "Numbers", "Lists"]
    >>> for index, title in enumerate(data_types):
@@ -105,11 +105,11 @@ List Comprehensions
 
 Üblicherweise wird eine Liste folgendermaßen generiert:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> squares = []
    >>> for i in range(8):
-   ...     squares.append(i ** 2)
+   ...     squares.append(i**2)
    ...
    >>> squares
    [0, 1, 4, 9, 16, 25, 36, 49]
@@ -118,9 +118,9 @@ Anstatt eine leere Liste zu erstellen und jedes Element am Ende einzufügen,
 definiert ihr mit List Comprehensions einfach die Liste und ihren Inhalt
 gleichzeitig mit nur einer einzigen Code-Zeile:
 
-.. code-block:: python
+.. code-block:: pycon
 
-   >>> squares = [i ** 2 for i in range(8)]
+   >>> squares = [i**2 for i in range(8)]
    >>> squares
    [0, 1, 4, 9, 16, 25, 36, 49]
 
@@ -145,8 +145,8 @@ Jede List Comprehension in Python enthält drei Elemente:
 Ihr könnt mit List Comprehensions auch optional Bedingungen verwenden, die
 üblicherweise am Ende des Ausdruck angehängt werden:
 
-.. code-block:: python
+.. code-block:: pycon
 
-   >>> squares = [i ** 2 for i in range(8) if i >= 4]
+   >>> squares = [i**2 for i in range(8) if i >= 4]
    >>> squares
    [16, 25, 36, 49]

docs/dataclasses.rst

@@ -16,7 +16,7 @@ Nehmen wir an, wir wollen eine Klasse speichern, die ein Item repräsentiert mit
 ``summary``, ``owner``, ``state`` und ``id``. Wir können eine solche Klasse
 definieren mit:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> from dataclasses import dataclass
    >>> @dataclass
@@ -25,12 +25,13 @@ definieren mit:
    ...     owner: str = None
    ...     state: str = "todo"
    ...     id: int = None
+   ...
 
 Der ``@dataclass``-Dekorator erstellt die ``__init__``- und
 ``__repr__``-Methoden. Wenn ich mir die Instanz der Klasse ausgeben lasse,
 erhalte ich den Klassennamen und die Attribute:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> i1
    Item(summary='My first item', owner='veit', state='todo', id=1)
@@ -41,15 +42,20 @@ zusätzliche Funktionalität verleihen, indem ihr Methoden definiert. Wir werden
 der Klasse eine Methode hinzufügen, die ein Item-Objekt aus einem :doc:`Dict
 <types/dicts>` erstellt:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> @dataclass
    ... class Item:
-   …
+   ...     ...
    ...     @classmethod
    ...     def from_dict(cls, d):
    ...         return Item(**d)
    ...
-   >>> item_dict = {"summary": "My first item", "owner": "veit", "state": "todo", "id": 1}
+   >>> item_dict = {
+   ...     "summary": "My first item",
+   ...     "owner": "veit",
+   ...     "state": "todo",
+   ...     "id": 1,
+   ... }
    >>> Item.from_dict(item_dict)
    Item(summary='My first item', owner='veit', state='todo', id=1)

docs/document/autodoc-examples.rst

@@ -0,0 +1,19 @@
+:orphan:
+
+``autodoc``-Beispiele
+=====================
+
+:py:mod:`string`-Modul
+----------------------
+
+.. automodule:: string
+
+:py:class:`string.Template`-Klasse
+----------------------------------
+
+.. autoclass:: string.Template
+
+:py:func:`string.capwords`-Funktion
+-----------------------------------
+
+.. autofunction:: string.capwords