Testen

reST-Formatierung

Ob die Sphinx-Dokumentation in gültigem reStructuredText-Format geschrieben ist, lässt sich mit sphinx-lint überprüfen. Dies binden wir üblicherweise in unsere pre-commit-Konfiguration ein:

.pre-commit-config.yaml
- repo: https://github.com/sphinx-contrib/sphinx-lint
  rev: v1.0.0
  hooks:
    - id: sphinx-lint
      types: [rst]

Siehe auch

Mit Sybil könnt ihr nicht nur reStructuredText überprüfen, sondern z.B. auch Markdown und Myst. Darüberhinaus kann Sybil auch Code-Blöcke in der Dokumentation entweder mit pytest oder mit Unittest überprüfen.

Code

Mit der eingebauten Python-Bibliothek Doctest könnt ihr auch Code in eurer Dokumentation mit der doctest.testfile()-Methode testen:

import doctest

doctest.testfile("example.rst")

Dieses kurze Skript führt alle interaktiven Python-Beispiele aus, die in der Datei example.rst enthalten sind, und überprüft sie. Der Inhalt der Datei wird so behandelt, als wäre er ein einziger riesiger Docstring.

Siehe auch

Ein einfaches Beispiel findet ihr in der Python-Dokumentation: Simple Usage: Checking Examples in a Text File.

Eine andere Möglichkeit, Code in Dokumentationen zu testen ist pytest-doctestplus.

Code-Formatierung

Die Formatierung von Code-Blöcken lässt sich mit blacken-docs überprüfen, das Black verwendet. Üblicherweise binden wir die Bibliothek über das pre-commit-Framework ein:

.pre-commit-config.yaml
- repo: https://github.com/adamchainz/blacken-docs
  rev: "v1.12.1"
  hooks:
  - id: blacken-docs
    additional_dependencies:
    - black

blacken-docs unterstützt aktuell die folgenden Black-Optionen:

Rechtschreibung

Die englische Rechtschreibung lässt sich überprüfen mit codespell. Es nutzt eine erweiterte Version der auf Wikipedia verfügbaren Wörterbücher. Ggf. könnt ihr jedoch auch eigene Wörterbücher mit der --builtin-Option bereitstellen.

Ihr könnt codespell in der pyproject.toml konfigurieren, z.B.:

pyproject.toml
[project.optional-dependencies]
docs = [
    "...",
    "codespell",
]

[tool.codespell]
ignore-words-list = "uint"
skip = "./.*, *.po, ./docs/_build"
count = true
quiet-level = 3

Ihr könnt codespell automatisch vor jedem Git-Commit ausführen, indem ihr folgendes in die .pre-commit-config.yaml-Datei eintragt:

.pre-commit-config.yaml
- repo: https://github.com/codespell-project/codespell
  rev: v2.3.0
  hooks:
    - id: codespell

Vale geht über Rechtschreib- und Grammatikprüfungen hinaus. Es überprüft auch den Sprachstil: Wiederholt sich das Gesagte? Ist die Sprache zu informell? Ist die Ansprache inkonsistent? Werden unerwünschte Klischees bedient? Oder ist die Sprache sexistisch?

Vale wird von vielen Open-Source-Projekten genutzt, u.a. von

Mit Vale selbst kommen die folgenden Stile mit:

Microsoft

Eine Implementierung des Microsoft Writing Style Guide.

Google

Eine Implementierung des Styleguides für den Google developer documentation style guide.

write-good

Eine Umsetzung der vom write-good-Linter erzwungenen Richtlinien.

proselint

Eine Umsetzung der vom proselint-Linter erzwungenen Richtlinien.

Joblint

Eine Umsetzung der vom Joblint-Linter erzwungenen Richtlinien.

Vale wird in der .vale.ini-Datei konfiguriert:

.vale.ini
StylesPath = styles
MinAlertLevel = suggestion

Packages = https://github.com/cusyio/cusy-vale/archive/refs/tags/v0.1.0.zip

[*.{md,rst}]
BasedOnStyles = cusy-de

Siehe auch

Anschließend solltet ihr ggf. eure .gitignore-Datei aktualisieren:

.gitignore
styles/*

Ihr könnt Vale für das pre-commit-Framework konfigurieren mit:

.pre-commit-config.yaml
- repo: https://github.com/errata-ai/vale
  rev: v3.7.1
  hooks:
  - id: vale sync
    pass_filenames: false
    args: [sync]
  - id: vale
    args: [--output=line, --minAlertLevel=error, .]

Docstrings-Coverage

interrogate prüft eure Codebasis auf fehlende Dokumentationsstrings und generiert ein shields.io-ähnliches Badge.

Ihr könnt interrogate z.B. in der pyproject.toml-Datei konfigurieren:

pyproject.toml
[project.optional-dependencies]
docs = [
    "...",
    "interrogate",
]

[tool.interrogate]
ignore-init-method = true
ignore-init-module = false
ignore-magic = false
ignore-semiprivate = false
ignore-private = false
ignore-module = false
ignore-property-decorators = false
fail-under = 95
exclude = ["tests/functional/sample", "setup.py", "docs"]
verbose = 0
omit-covered-files = false
quiet = false
whitelist-regex = []
ignore-regex = []
color = true

Siehe auch

Nun könnt ihr interrogate in eure tox-Datei einfügen, z.B. mit

tox.ini
[testenv:doc]
deps = interrogate
skip_install = true
commands =
    interrogate --quiet --fail-under 95 src tests

Ihr könnt interrogate auch mit pre-commit nutzen:

.pre-commit-config.yaml
repos:
  - repo: https://github.com/econchick/interrogate
    rev: 1.7.0
    hooks:
      - id: interrogate
        args: [--quiet, --fail-under=95]
        pass_filenames: false