Merge branch 'main' into 683-trigger-scheduler-api-endpoint-fails-to-…

…save-the-results-to-the-database-on-subsequent-calls

.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

.vscode/spellright.dict

@@ -251,3 +251,8 @@ Changelog
 Bugfixes
 Dockerfile
 nt
+Backoffice
+eval
+dataframe
+dataframes
+args

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 ---
 

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 %}

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

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`.
 
 
 

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/api/dev/__init__.py

@@ -1,3 +1,7 @@
+"""
+Endpoints under development. Use at your own risk.
+"""
+
 from flask import Flask
 
 

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)

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 (

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 (

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 (

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 (

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 (

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/tests/__init__.py

@@ -0,0 +1 @@
+""" Higher-level tests """