From 4891f106b2b3177120ed8ca9bfed2e24d1108164 Mon Sep 17 00:00:00 2001 From: Veit Schiele Date: Thu, 2 May 2024 14:57:23 +0200 Subject: [PATCH] :wrench: Add tests for documentation * Fix syntax in a code-block --- .github/workflows/ci.yml | 31 +++++++++ .github/workflows/pre-commit.yml | 18 ----- .pre-commit-config.yaml | 13 +++- docs/document/docstrings.rst | 7 +- docs/document/extensions.rst | 8 +-- docs/document/uml/index.rst | 111 +++++++++++++++---------------- docs/test/coverage.rst | 4 +- docs/test/pytest/fixtures.rst | 2 + docs/test/pytest/params.rst | 8 ++- docs/test/unittest2.rst | 4 +- 10 files changed, 112 insertions(+), 94 deletions(-) create mode 100644 .github/workflows/ci.yml delete mode 100644 .github/workflows/pre-commit.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..c75a677 --- /dev/null +++ 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 deleted file mode 100644 index cd1b418..0000000 --- a/.github/workflows/pre-commit.yml +++ /dev/null @@ -1,18 +0,0 @@ -name: pre-commit - -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.0 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index cfc072b..289a3a7 100644 --- 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 index e75e11d..5386e22 100644 --- 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 index b46a0ca..d380a07 100644 --- 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 index 010b17c..6ccdf26 100644 --- a/docs/document/uml/index.rst +++ b/docs/document/uml/index.rst @@ -1,57 +1,54 @@ -Unified Modeling Language (UML) -=============================== - -Installation ------------- - -#. Installiert `plantuml `_: - - .. tab:: Linux - - .. code-block:: console - - $ sudo apt install plantuml - - .. tab:: macOS - - .. code-block:: console - - $ brew install plantuml - -#. Installiert `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 `_: + + .. tab:: Linux + + .. code-block:: console + + $ sudo apt install plantuml + + .. tab:: macOS + + .. code-block:: console + + $ brew install plantuml + +#. Installiert `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 index f10bec3..6a5185a 100644 --- 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 index e0158c3..6d29f09 100644 --- 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 index 41af477..f80ae35 100644 --- 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 index 7b474c0..09a3110 100644 --- 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