🔧 Add tests for documentation

* Fix reST syntax
* Fix syntax in a code-block
* Add linkcheck ignore, exclude and redirects lists
* Fix broken links and redirects
* 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

@@ -9,6 +9,7 @@ repos:
     - id: check-yaml
     - id: check-added-large-files
       args: ['--maxkb=1024']
+
   - repo: https://github.com/pycqa/isort
     rev: 5.13.2
     hooks:
@@ -26,3 +27,10 @@ repos:
     - 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,21 +13,21 @@ following string constants, all of which fall into the ASCII character set:
 .. 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
 
 Most of these constants should be self-explanatory in their identifier names.
 ``hexdigits`` and ``octdigits`` refer to the hexadecimal and octal values
 respectively. You can use these constants for everyday string manipulation:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> import string
     >>> hepy = "Hello Pythonistas!"
@@ -78,7 +78,7 @@ human-readable text and can contain all Unicode characters. The :ref:`bytes
 inherently encoded. :meth:`python3:str.encode` and :meth:`python3:bytes.decode`
 are the methods of transition from one to the other:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> "You’re welcome!".encode("utf-8")
     b'You\xe2\x80\x99re welcome!'
@@ -100,9 +100,9 @@ bytes, ``e2``, ``80`` and ``99`` as hexadecimal values.
 With :meth:`python3:bytes.fromhex` you can convert the hexadecimal values into
 bytes:
 
-.. code-block:: python
+.. code-block:: pycon
 
-    >>> bytes.fromhex('e2 80 99')
+    >>> bytes.fromhex("e2 80 99")
     b'\xe2\x80\x99'
 
 UTF-16 and UTF-32
@@ -112,7 +112,7 @@ The difference between these and UTF-8 is considerable in practice. In the
 following, I would like to show you only briefly by means of an example that a
 round-trip conversion can simply fail here:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> hepy = "Hello Pythonistas!"
     >>> hepy.encode("utf-8")
@@ -149,7 +149,7 @@ The only exception could be :func:`open() <python3:open>`, which is platform
 dependent and therefore depends on the value of
 :func:`python3:locale.getpreferredencoding`:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> import locale
     >>> locale.getpreferredencoding()

docs/control-flows/boolean.rst

@@ -14,7 +14,7 @@ example, the empty list ``[]`` or the empty string ``""``) are all considered
 ``and``, ``not``, ``or``
     are logical operators that can be used to link the above checks.
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> x = 3
    >>> y = 3.0
@@ -40,7 +40,7 @@ referring to the same object in two places.
 Most frequently, ``is`` and ``is not`` are used in conjunction with
 :doc:`../types/none`:
 
-.. code-block:: python
+.. code-block:: pycon
 
     >>> x is None
     False
@@ -54,7 +54,7 @@ is None`` instead.
 However, you should never compare calculated floating point numbers with each
 other:
 
-.. 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 @@ The code block after the first true condition of an ``if`` or ``elif`` statement
 is executed. If none of the conditions are true, the code block after the
 ``else`` is executed:
 
-.. code-block:: python
+.. code-block:: pycon
     :linenos:
 
     >>> x = 1

docs/control-flows/loops.rst

@@ -7,7 +7,7 @@ Loops
 The ``while`` loop is executed as long as the condition (here: ``x > y``) is
 true:
 
-.. code-block:: python
+.. code-block:: pycon
     :linenos:
 
     >>> x, y = 6, 3
@@ -35,7 +35,7 @@ Lines 8 and 9
     outputs the results of the ``while`` loop before execution was interrupted
     with ``break``.
 
-.. code-block:: python
+.. code-block:: pycon
     :linenos:
 
     >>> x, y = 6, 3
@@ -64,7 +64,7 @@ a foreach loop. The following loop uses the `Modulo
 <https://en.wikipedia.org/wiki/Modulo_operation>`_ operator ``%`` as a condition
 for the first occurrence of an integer divisible by ``5``:
 
-.. code-block:: python
+.. code-block:: pycon
     :linenos:
 
     >>> items = [1, "fünf", 5.0, 10, 11, 15]
@@ -90,7 +90,7 @@ Loops with an index
 You can also output the index in a ``for`` loop, for example with
 :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
 
 A list is usually generated as follows:
 
-.. 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 @@ Instead of creating an empty list and inserting each element at the end, with
 list comprehensions you simply define the list and its content at the same time
 with just a single line of code:
 
-.. 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 @@ Each list comprehension in Python contains three elements:
 You can also use optional conditions with list comprehensions, which are usually
 appended to the end of the expression:
 
-.. 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

@@ -1,9 +1,10 @@
 ``dataclasses``
 ===============
 
-:doc:`dataclasses <python3:library/dataclasses>` were introduced in Python 3.7 and are a
-special shortcut with which we can create classes that store data. Python offers a special
-:doc:`decorator <functions/decorators>` if we want to create such a class.
+:doc:`dataclasses <python3:library/dataclasses>` were introduced in Python 3.7
+and are a special shortcut with which we can create classes that store data.
+Python offers a special :doc:`decorator <functions/decorators>` if we want to
+create such a class.
 
 .. note::
    For table data I generally use :doc:`pandas Series or DataFrames
@@ -14,7 +15,7 @@ special shortcut with which we can create classes that store data. Python offers
 Let’s say we want to store a class that represents an item with ``summary``,
 ``owner``, ``state`` and ``id``. We can define such a class with:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> from dataclasses import dataclass
    >>> @dataclass
@@ -23,11 +24,12 @@ Let’s say we want to store a class that represents an item with ``summary``,
    ...     owner: str = None
    ...     state: str = "todo"
    ...     id: int = None
+   ...
 
 The ``@dataclass`` decorator creates the ``__init__`` and ``__repr__`` methods.
 If I display the instance of the class, I get the class name and the attributes:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> i1
    Item(summary='My first item', owner='veit', state='todo', id=1)
@@ -37,15 +39,20 @@ store data. You can add extra functionality to your classes by defining methods.
 We will add a method to the class that creates an Item object from a
 :doc:`Dict <types/dicts>`:
 
-.. 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/docstrings.rst

@@ -21,10 +21,7 @@ file  ``docs/conf.py``:
 
 .. code-block:: python
 
-    extensions = [
-        'sphinx.ext.autodoc',
-        ...
-    ]
+    extensions = ["sphinx.ext.autodoc", ...]
 
 If your package and its documentation are part of the same repository, they will
 always have the same relative position in the filesystem. In this case you can
@@ -33,7 +30,7 @@ path to the package, so:
 
 .. code-block:: python
 
-    sys.path.insert(0, os.path.abspath('..'))
+    sys.path.insert(0, os.path.abspath(".."))
     import requests
 
 If you have installed your Sphinx documentation in a virtual environment, you

docs/document/extensions.rst

@@ -106,12 +106,10 @@ If your extension is in the directory ``exts`` in the file ``foo.py``, then the
 
     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

docs/document/intersphinx.rst

@@ -13,26 +13,24 @@ In ``docs/conf.py`` Intersphinx must be indicated as an extension:
 .. code-block:: python
 
     extensions = [
-        ...
-        'sphinx.ext.intersphinx',
-        ]
+        "sphinx.ext.intersphinx",
+    ]
 
 External Sphinx documentation can then be specified, e.g. with:
 
 .. code-block:: python
 
     intersphinx_mapping = {
-        'python': ('https://docs.python.org/3', None),
-        'bokeh':  ('https://bokeh.pydata.org/en/latest/', None)
+        "python": ("https://docs.python.org/3", None),
+        "bokeh": ("https://bokeh.pydata.org/en/latest/", None),
     }
 
 However, alternative files can also be specified for an inventory, for example:
 
 .. code-block:: python
 
     intersphinx_mapping = {
-        'python': ('https://docs.python.org/3', (None, 'python-inv.txt'),
-        ...
+        "python": ("https://docs.python.org/3", None, "python-inv.txt"),
     }
 
 Determine link targets