docs: Automatic Code Documentation

.vscode/spellright.dict

@@ -251,3 +251,4 @@ Changelog
 Bugfixes
 Dockerfile
 nt
+Backoffice

Makefile

@@ -18,14 +18,14 @@ update-docs:
 	@echo "Creating docs environment ..."
 	make install-docs-dependencies
 	@echo "Creating documentation ..."
-	cd documentation; make clean; make html SPHINXOPTS="-W --keep-going -n"; cd ..
+	export GEN_CODE_DOCS=${gen_code_docs}; cd documentation; make clean; make html SPHINXOPTS="-W --keep-going -n"; cd ..
 
 update-docs-pdf:
 	@echo "NOTE: PDF documentation requires packages (on Debian: latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended)"
 	@echo "NOTE: Currently, the docs require some pictures which are not in the git repo atm. Ask the devs."
 	make install-sphinx-tools
 
-	cd documentation; make clean; make latexpdf; make latexpdf; cd ..  # make latexpdf can require two passes
+	export GEN_CODE_DOCS=${gen_code_docs}; cd documentation; make clean; make latexpdf; make latexpdf; cd ..  # make latexpdf can require two passes
 
 # ---- Installation ---
 

documentation/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+.. Adapted from https://stackoverflow.com/a/62613202
+{{ fullname | escape | underline}}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst                
+   :recursive:
+{% for item in modules %}
+   {% if "test" not in item %}
+   {{ item }}
+   {% endif %}
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+
+   {% for item in attributes %}
+   .. autoattribute::
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   {% for item in functions %}
+   .. autofunction::
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   {% for item in classes %}     
+   .. autoclass:: {{ item }}
+      :members:
+      :special-members: __init__
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   {% for item in exceptions %}
+   .. autoexception::
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

documentation/conf.py

@@ -6,6 +6,8 @@
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/stable/config
 
+import os
+
 from datetime import datetime
 from pkg_resources import get_distribution
 import sphinx_fontawesome
@@ -52,11 +54,20 @@
     "sphinx_fontawesome",
     "sphinxcontrib.autohttp.flask",
     "sphinxcontrib.autohttp.flaskqref",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autodoc.typehints",
 ]
 
+autodoc_default_options = {}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# generate autosummary even if no references
+autosummary_generate = bool(
+    os.environ.get("GEN_CODE_DOCS", "False").lower() in ("t", "true", "1")
+)
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -76,7 +87,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "_templates"]
 
 # Todo: these are not mature enough yet for release, or should be removed
 exclude_patterns.append("int/*.rst")
@@ -224,3 +235,9 @@ def setup(sphinx_app):
         "live",
         "env",  # hard-coded, documentation is not server-specific for the time being
     )
+
+    if autosummary_generate:
+
+        from flexmeasures.app import create
+
+        create()  # we need to create the app for when sphinx imports modules that use current_app

documentation/index.rst

@@ -249,11 +249,19 @@ The platform operator of FlexMeasures can be an Aggregator.
     dev/docker-compose
 
 
+.. autosummary::
+   :caption: Code Documentation
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
 
-Code documentation
-------------------
+   flexmeasures
 
-Go To :ref:`source`.
+
+.. Code documentation
+.. ------------------
+
+.. Go To :ref:`source`.
 
 
 

flexmeasures/api/__init__.py

@@ -1,3 +1,7 @@
+"""
+FlexMeasures API routes and implementations.
+"""
+
 from flask import Flask, Blueprint, request
 from flask_security.utils import verify_password
 from flask_json import as_json

flexmeasures/app.py

@@ -1,3 +1,7 @@
+"""
+Starting point of the Flask application.
+"""
+
 from __future__ import annotations
 
 import time

flexmeasures/auth/__init__.py

@@ -1,3 +1,7 @@
+"""
+Authentication and authorization policies and helpers.
+"""
+
 from flask import Flask
 from flask_security import Security, SQLAlchemySessionUserDatastore
 from flask_login import user_logged_in, current_user
@@ -6,11 +10,6 @@
 from flexmeasures.data import db
 
 
-"""
-Configure authentication and authorization.
-"""
-
-
 def register_at(app: Flask):
 
     from flexmeasures.auth.error_handling import (

flexmeasures/cli/__init__.py

@@ -1,3 +1,7 @@
+"""
+CLI functions for FlexMeasures hosts.
+"""
+
 import sys
 
 from flask import Flask, current_app

flexmeasures/data/__init__.py

@@ -1,3 +1,7 @@
+"""
+Models & schemata, as well as business logic (queries & services).
+"""
+
 import os
 
 from flask import Flask

flexmeasures/ui/__init__.py

@@ -1,3 +1,7 @@
+"""
+Backoffice user interface & charting support.
+"""
+
 import os
 
 from flask import current_app, Flask, Blueprint