From 28d44ca764955cb042e5d1821ffc23e2b9aba07c Mon Sep 17 00:00:00 2001 From: Daniel Schadt Date: Thu, 29 Dec 2022 16:20:18 +0100 Subject: generate & build API docs for the Python package We have so many nice docstrings, but they aren't really rendered anywhere (expect locally in your IDE), as we did not include the API docs anywhere. This change uses sphinx-apidoc to generate autodoc stubs for Sphinx, so that the docstrings are actually rendered to HTML. This is not perfect yet (I'm not too happy about the default modules.rst simply listing one package), but it is good enough for the start and makes it possible to actually browse the docstrings in a browser. --- .gitignore | 2 ++ doc/conf.py | 1 + doc/developer.rst | 1 + fietsboek/__init__.py | 18 +++++++++++++++--- fietsboek/scripts/fietsctl.py | 6 ++++-- poetry.lock | 22 +++++++++++++++++++++- pyproject.toml | 1 + tox.ini | 1 + 8 files changed, 46 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 259f717..4ff2054 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,5 @@ test /data poetry.toml /language-packs +# The module docs are regenerated using sphinx-apidoc +doc/developer/module/ diff --git a/doc/conf.py b/doc/conf.py index 7769cf1..d2d3cf3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -30,6 +30,7 @@ author = 'Daniel Schadt' extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', + 'sphinx_autodoc_typehints', ] intersphinx_mapping = { diff --git a/doc/developer.rst b/doc/developer.rst index b47b0a4..f6546ab 100644 --- a/doc/developer.rst +++ b/doc/developer.rst @@ -7,6 +7,7 @@ Developer Guide developer/localize developer/language-pack + Python Packages This guide contains information for developers that want to modify or extend Fietsboek. This includes information on how to localize Fietsboek to new diff --git a/fietsboek/__init__.py b/fietsboek/__init__.py index 0e9399c..fed720b 100644 --- a/fietsboek/__init__.py +++ b/fietsboek/__init__.py @@ -1,6 +1,17 @@ """Fietsboek is a web application to track and share GPX tours. -For more information, see the README or the included documentation. +This is the documentation for the Python package, useful for developers that +wish to work on fietsboek. + +For more information, you can check out the following resources: + +* The `Fietsboek repository`_. +* The documentation index: :doc:`../../../index` + +.. _Fietsboek repository: https://gitlab.com/dunj3/fietsboek + +Content +------- """ from pathlib import Path @@ -24,11 +35,12 @@ def locale_negotiator(request): """Negotiates the right locale to use. This tries the following: + 1. It runs the default negotiator. This allows the locale to be overriden - by using the _LOCALE_ query parameter. + by using the ``_LOCALE_`` query parameter. 2. It uses the `Accept-Language`_ header. - .. Accept-Language: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language + .. _Accept-Language: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language :param request: The request for which to get the language. :type request: pyramid.request.Request diff --git a/fietsboek/scripts/fietsctl.py b/fietsboek/scripts/fietsctl.py index b5e1036..774768c 100644 --- a/fietsboek/scripts/fietsctl.py +++ b/fietsboek/scripts/fietsctl.py @@ -93,9 +93,11 @@ def cmd_userdel(env, args): def cmd_userlist(env, args): """Prints a listing of all user accounts. - The format is + The format is:: + [av] {ID} - {email} - {Name} - one line per user. The 'a' is added for admin accounts, the 'v' is added + + with one line per user. The 'a' is added for admin accounts, the 'v' is added for verified users. """ with env["request"].tm: diff --git a/poetry.lock b/poetry.lock index 34ab30c..519746c 100644 --- a/poetry.lock +++ b/poetry.lock @@ -943,6 +943,22 @@ docs = ["sphinxcontrib-websupport"] lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-bugbear", "flake8-comprehensions", "flake8-simplify", "isort", "mypy (>=0.981)", "sphinx-lint", "types-requests", "types-typed-ast"] test = ["cython", "html5lib", "pytest (>=4.6)", "typed_ast"] +[[package]] +name = "sphinx-autodoc-typehints" +version = "1.19.5" +description = "Type hints (PEP 484) support for the Sphinx autodoc extension" +category = "dev" +optional = false +python-versions = ">=3.7" + +[package.dependencies] +sphinx = ">=5.3" + +[package.extras] +docs = ["furo (>=2022.9.29)", "sphinx (>=5.3)", "sphinx-autodoc-typehints (>=1.19.4)"] +testing = ["covdefaults (>=2.2)", "coverage (>=6.5)", "diff-cover (>=7.0.1)", "nptyping (>=2.3.1)", "pytest (>=7.2)", "pytest-cov (>=4)", "sphobjinv (>=2.2.2)", "typing-extensions (>=4.4)"] +type-comment = ["typed-ast (>=1.5.4)"] + [[package]] name = "sphinxcontrib-applehelp" version = "1.0.2" @@ -1332,7 +1348,7 @@ test = ["zope.testing"] [metadata] lock-version = "1.1" python-versions = "^3.7.2" -content-hash = "409175c4ab450ddc362d21b89a10f181b634469077586b046f8a5b9f028bb0e2" +content-hash = "64f7cc3d3de5c7fa19c23d20989e237df137db4cd80abf433154e1ad94c345f5" [metadata.files] alabaster = [ @@ -2023,6 +2039,10 @@ sphinx = [ {file = "Sphinx-5.3.0.tar.gz", hash = "sha256:51026de0a9ff9fc13c05d74913ad66047e104f56a129ff73e174eb5c3ee794b5"}, {file = "sphinx-5.3.0-py3-none-any.whl", hash = "sha256:060ca5c9f7ba57a08a1219e547b269fadf125ae25b06b9fa7f66768efb652d6d"}, ] +sphinx-autodoc-typehints = [ + {file = "sphinx_autodoc_typehints-1.19.5-py3-none-any.whl", hash = "sha256:ea55b3cc3f485e3a53668bcdd08de78121ab759f9724392fdb5bf3483d786328"}, + {file = "sphinx_autodoc_typehints-1.19.5.tar.gz", hash = "sha256:38a227378e2bc15c84e29af8cb1d7581182da1107111fd1c88b19b5eb7076205"}, +] sphinxcontrib-applehelp = [ {file = "sphinxcontrib-applehelp-1.0.2.tar.gz", hash = "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"}, {file = "sphinxcontrib_applehelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a"}, diff --git a/pyproject.toml b/pyproject.toml index 292351a..4763834 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,6 +61,7 @@ optional = true [tool.poetry.group.docs.dependencies] Sphinx = "^5.3" +sphinx-autodoc-typehints = "^1.19.5" [tool.poetry.group.testing] optional = true diff --git a/tox.ini b/tox.ini index a31e865..86909c4 100644 --- a/tox.ini +++ b/tox.ini @@ -49,6 +49,7 @@ changedir={toxinidir}{/}doc commands_pre = poetry install -v --with docs commands = + sphinx-apidoc -d 1 -f -M -e -o developer/module/ ../fietsboek "upd_*" make html [testenv:mypy] -- cgit v1.2.3