docs: Automatic Code Documentation (#698)

* docs: automatic generation of code documentation Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * docs: class and module templates Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * fix: simplify generated docs Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * feat: switch on/off generation of code docs via the parameter gen_code_docs of the makefile command update-docs and update-docs-pdf Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * add docstrings for main modules Signed-off-by: Nicolas Höning <nicolas@seita.nl> * Add docstrings to API modules Signed-off-by: Nicolas Höning <nicolas@seita.nl> * fix: add autodoc and autosmmary when GEN_CODE_DOCS=True Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * fix: set gen_code_docs default to True and False for devs (calling update-docs using make) Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * move single test from config package into new tests package Signed-off-by: Nicolas Höning <nicolas@seita.nl> * fix: show main modules Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * fix: remove documentation/_autosummary when gen_code_docs=False Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * fix: make generated rst to live under _autosummary/ folder Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * add autosummary folder to .gitignore Signed-off-by: Nicolas Höning <nicolas@seita.nl> * add some spellright words Signed-off-by: Nicolas Höning <nicolas@seita.nl> * try setting FLASK_ENV during RTD building Signed-off-by: Nicolas Höning <nicolas@seita.nl> * fix: set a fake SQLALCHEMY_DATABASE_URI Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * no need to look for config file when building documentation Signed-off-by: Nicolas Höning <nicolas@seita.nl> * also export SECRET_KEY in RTD Signed-off-by: Nicolas Höning <nicolas@seita.nl> * test add SECRET_KEY Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * docs: add private methods Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * test only with env variables set in conf.py Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * test Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * fix: remove exports Signed-off-by: Victor Garcia Reolid <victor@seita.nl> * re-do a change to a comment that is by now inaccurate and improve the comment, as well Signed-off-by: Nicolas Höning <nicolas@seita.nl> --------- Signed-off-by: Victor Garcia Reolid <victor@seita.nl> Signed-off-by: Nicolas Höning <nicolas@seita.nl> Co-authored-by: Nicolas Höning <nicolas@seita.nl>
FlexMeasures · Jun 9, 2023 · a02c9cd · a02c9cd
1 parent 726cd32
commit a02c9cd
Show file tree

Hide file tree

Showing 25 changed files with 182 additions and 91 deletions.
diff --git a/.gitignore b/.gitignore
@@ -29,6 +29,7 @@ notebooks/.ipynb_checkpoints/
 
 flexmeasures/ui/static/documentation
 documentation/img/screenshot_*
+documentation/_autosummary/
 generic_asset_fm_user_ownership.sql
 
 uml_diagram.png

diff --git a/.vscode/spellright.dict b/.vscode/spellright.dict
@@ -251,3 +251,8 @@ Changelog
 Bugfixes
 Dockerfile
 nt
+Backoffice
+eval
+dataframe
+dataframes
+args
diff --git a/Makefile b/Makefile
@@ -14,18 +14,20 @@ test:
 
 # ---- Documentation ---
 
+gen_code_docs := False # by default code documentation is not generated
+
 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 ---
 

diff --git a/documentation/_templates/custom-module-template.rst b/documentation/_templates/custom-module-template.rst
@@ -0,0 +1,67 @@
+.. 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__
+      :private-members:
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   {% for item in exceptions %}
+   .. autoexception::
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/documentation/conf.py b/documentation/conf.py
@@ -6,6 +6,9 @@
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/stable/config
 
+import os
+import shutil
+
 from datetime import datetime
 from pkg_resources import get_distribution
 import sphinx_fontawesome
@@ -41,7 +44,6 @@
 # ones.
 extensions = [
     "sphinx_rtd_theme",
-    "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.imgmath",
@@ -54,9 +56,32 @@
     "sphinxcontrib.autohttp.flaskqref",
 ]
 
+autodoc_default_options = {}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# if GEN_CODE_DOCS is not found, the default is gen_code_docs=True
+gen_code_docs = not bool(
+    os.environ.get("GEN_CODE_DOCS", "True").lower() in ("f", "false", "0")
+)
+
+
+# Generate code docs
+if gen_code_docs:
+
+    # Add dependencies
+    extensions.extend(
+        [
+            "sphinx.ext.autosummary",
+            "sphinx.ext.autodoc.typehints",
+            "sphinx.ext.autodoc",
+        ]
+    )
+else:
+    if os.path.exists("_autosummary"):
+        shutil.rmtree("_autosummary")
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -76,7 +101,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 +249,10 @@ def setup(sphinx_app):
         "live",
         "env",  # hard-coded, documentation is not server-specific for the time being
     )
+
+    if gen_code_docs:
+        from flexmeasures.app import create
+
+        create(
+            env="documentation"
+        )  # we need to create the app for when sphinx imports modules that use current_app
diff --git a/documentation/index.rst b/documentation/index.rst
@@ -249,11 +249,25 @@ 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.api
+   flexmeasures.app
+   flexmeasures.auth
+   flexmeasures.cli
+   flexmeasures.data
+   flexmeasures.ui
+   flexmeasures.utils
 
-Go To :ref:`source`.
+
+.. Code documentation
+.. ------------------
+
+.. Go To :ref:`source`.
 
 
 

diff --git a/documentation/source.rst b/documentation/source.rst
diff --git a/flexmeasures/api/__init__.py b/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

diff --git a/flexmeasures/api/dev/__init__.py b/flexmeasures/api/dev/__init__.py
@@ -1,3 +1,7 @@
+"""
+Endpoints under development. Use at your own risk.
+"""
+
 from flask import Flask
 
 

diff --git a/flexmeasures/api/play/__init__.py b/flexmeasures/api/play/__init__.py
@@ -1,3 +1,7 @@
+"""
+Endpoints to support "play" mode, e.g. with data restorable.
+"""
+
 from flask import Flask, Blueprint
 
 # The api blueprint. It is registered with the Flask app (see app.py)

diff --git a/flexmeasures/api/v1/__init__.py b/flexmeasures/api/v1/__init__.py
@@ -1,3 +1,7 @@
+"""
+This API version is sunset.
+"""
+
 from flask import Flask, Blueprint
 
 from flexmeasures.api.common.utils.deprecation_utils import (

diff --git a/flexmeasures/api/v1_1/__init__.py b/flexmeasures/api/v1_1/__init__.py
@@ -1,3 +1,7 @@
+"""
+This API version is sunset.
+"""
+
 from flask import Flask, Blueprint
 
 from flexmeasures.api.common.utils.deprecation_utils import (

diff --git a/flexmeasures/api/v1_2/__init__.py b/flexmeasures/api/v1_2/__init__.py
@@ -1,3 +1,7 @@
+"""
+This API version is sunset.
+"""
+
 from flask import Flask, Blueprint
 
 from flexmeasures.api.common.utils.deprecation_utils import (

diff --git a/flexmeasures/api/v1_3/__init__.py b/flexmeasures/api/v1_3/__init__.py
@@ -1,3 +1,7 @@
+"""
+This API version is sunset.
+"""
+
 from flask import Flask, Blueprint
 
 from flexmeasures.api.common.utils.deprecation_utils import (

diff --git a/flexmeasures/api/v2_0/__init__.py b/flexmeasures/api/v2_0/__init__.py
@@ -1,3 +1,7 @@
+"""
+This API version is sunset.
+"""
+
 from flask import Flask, Blueprint
 
 from flexmeasures.api.common.utils.deprecation_utils import (

diff --git a/flexmeasures/app.py b/flexmeasures/app.py
@@ -1,3 +1,7 @@
+"""
+Starting point of the Flask application.
+"""
+
 from __future__ import annotations
 
 import time

diff --git a/flexmeasures/auth/__init__.py b/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 (

diff --git a/flexmeasures/cli/__init__.py b/flexmeasures/cli/__init__.py
@@ -1,3 +1,7 @@
+"""
+CLI functions for FlexMeasures hosts.
+"""
+
 import sys
 
 from flask import Flask, current_app

diff --git a/flexmeasures/config/__init__.py b/flexmeasures/config/__init__.py
diff --git a/flexmeasures/config/tests/__init__.py b/flexmeasures/config/tests/__init__.py
diff --git a/flexmeasures/data/__init__.py b/flexmeasures/data/__init__.py
@@ -1,3 +1,7 @@
+"""
+Models & schemata, as well as business logic (queries & services).
+"""
+
 import os
 
 from flask import Flask

diff --git a/flexmeasures/tests/__init__.py b/flexmeasures/tests/__init__.py
@@ -0,0 +1 @@
+""" Higher-level tests """
diff --git a/flexmeasures/config/tests/test_package.py → ...res/tests/test_highlevel_class_imports.py b/flexmeasures/config/tests/test_package.py → ...res/tests/test_highlevel_class_imports.py