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.

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 <developer/module/modules>
 
 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
@@ -944,6 +944,22 @@ lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-bugbear", "flake8-comprehe
 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"
 description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books"
@@ -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]