🔧 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
veit · May 5, 2024 · 55550b0 · 55550b0
1 parent 1e83531
commit 55550b0
Show file tree

Hide file tree

Showing 53 changed files with 554 additions and 435 deletions.
diff --git a/.github/workflows/ci.yml b/.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
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
@@ -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
diff --git a/docs/appendix/encodings.rst b/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()

diff --git a/docs/conf.py b/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",
@@ -49,26 +49,70 @@
 
 intersphinx_mapping = {
     "python3": ("https://docs.python.org/3/", None),
-    "jupyter-tutorial": ("https://jupyter-tutorial.readthedocs.io/en/latest/", None),
-    "Python4DataScience": ("https://www.python4data.science/en/latest/", None),
+    "jupyter-tutorial": ("https://jupyter-tutorial.readthedocs.io/de/latest/", None),
+    "Python4DataScience": ("https://www.python4data.science/de/latest/", None),
     "pytest": ("https://docs.pytest.org/en/latest/", None),
     "Sybil": ("https://sybil.readthedocs.io/en/latest/", None),
 }
 
+linkcheck_ignore = [
+    r".*/_sources/.*/*.txt",
+    # 403 Client Error
+    r"https://anaconda.org/",
+]
+
+# All HTTP redirections from the source URI to the canonical URI will be treated# as "working".
+linkcheck_allowed_redirects = {
+    r"https://devpi\.net/docs/$": r"https://devpi\.net/docs/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://click.palletsprojects.com/$": r"https://click.palletsprojects.com/[-a-z]+/(\d+\.)?(\d+\.)?(x|\d+)/$",
+    # Unfortunately, the following regular expression fails: invalid group
+    # reference 1. Therefore, the redirects for readthedocs must unfortunately
+    # be specified individually.
+    # r"https://([^/?#\.]+)\.readthedocs\.io/$": r"https://\1\.readthedocs\.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://cffi.readthedocs.io/$": r"https://cffi.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://cookiecutter.readthedocs.io/$": r"https://cookiecutter.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://faker.readthedocs.io/$": r"https://faker.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://hypothesis.readthedocs.io/$": r"https://hypothesis.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://nbsphinx.readthedocs.io/$": r"https://nbsphinx.readthedocs.io/[-a-z]+/(\d+\.)?(\d+\.)?(x|\d+)/$",
+    r"https://cibuildwheel.pypa.io/$": r"https://cibuildwheel.pypa.io/[-a-z]+/(?:latest|stable|master)/$",
+    # r"https://docs.pytest.org/$": r"https://docs.pytest.org/[-a-z]+/(\d+\.)?(\d+\.)?(x|\d+)/$",
+    r"https://docs.pytest.org/$": r"https://docs.pytest.org/[-a-z]+/(?:latest|stable|master|(\d+\.)?(\d+\.)?(x|\d+))/$",
+    r"https://docs.python.org/$": r"https://docs.python.org/3/$",
+    r"https://gist.github.com": r"https://gist.github.com/.*",
+    r"https://flit.pypa.io": r"https://flit.pypa.io/.*",
+    r"https://docs.sqlalchemy.org": r"https://docs.sqlalchemy.org/[-a-z]+/(\d+\.)?(\d+\.)?(x|\d+)/$",
+    r"https://github.com/settings/tokens": r"https://github.com/login?.*",
+    r"https://github.com/veit/python-basics-tutorial-de/fork": r"https://github.com/login?.*",
+    r"https://jinja.palletsprojects.com/$": r"https://jinja.palletsprojects.com/[-a-z]+/(?:latest|stable|master|(\d+\.)?(\d+\.)?(x|\d+))/$",
+    r"https://pdm.fming.dev/$": r"https://pdm-project.org/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://pip.pypa.io/$": r"https://pip.pypa.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://pypi.org/manage/account/publishing/": r"https://pypi.org/account/login/.*",
+    r"https://pytest-cov.readthedocs.io/$": r"https://pytest-cov.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://setuptools.readthedocs.io/$": r"https://setuptools.pypa.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://sphinx-git.readthedocs.io/$": r"https://sphinx-git.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://sphinxcontrib-napoleon.readthedocs.io/$": r"https://sphinxcontrib-napoleon.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://sphinx-needs.readthedocs.io/$": r"https://sphinx-needs.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://tox.readthedocs.io/$": r"https://tox.wiki/[-a-z]+/(\d+\.)?(\d+\.)?(x|\d+)/$",
+    r"https://wheel.readthedocs.io/$": r"https://wheel.readthedocs.io/[-a-z]+/(?:latest|stable|master)/$",
+    r"https://www.sphinx-doc.org/$": r"https://www.sphinx-doc.org/[-a-z]+/(?:latest|stable|master)/$",
+}
+
+linkcheck_exclude_documents = [r".*/dataprep/.*"]
+
 # 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.
 master_doc = "index"
 
 # General information about the project.
-project = "Python basics"
+project = "Python Basics"
 author = "Veit Schiele"
 copyright = f"2021–2024, {author}"
 
@@ -113,7 +157,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 +173,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
@@ -149,7 +193,7 @@
     (
         master_doc,
         "python-basics.tex",
-        "Python basics",
+        "Python Basics",
         "Veit Schiele",
         "manual",
     ),
@@ -160,7 +204,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "python-basics", "Python basics", [author], 1)]
+man_pages = [(master_doc, "python-basics", "Python Basics", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------
@@ -172,10 +216,10 @@
     (
         master_doc,
         "python-basics",
-        "Python basics",
+        "Python Basics",
         author,
         "python-basics",
-        "Python basics.",
+        "Python Basics.",
         "Miscellaneous",
     ),
 ]
diff --git a/docs/control-flows/boolean.rst b/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

diff --git a/docs/control-flows/if-elif-else.rst b/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