Merge branch 'main' into feature/aggregation-reporter

FlexMeasures · Jun 9, 2023 · f9a876a · f9a876a
2 parents 3983b2b + a02c9cd
commit f9a876a
Show file tree

Hide file tree

Showing 30 changed files with 248 additions and 119 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/changelog.rst b/documentation/changelog.rst
@@ -13,6 +13,7 @@ New features
 * Introduction of the classes `Reporter` and `PandasReporter` [see `PR #641 <https://www.github.com/FlexMeasures/flexmeasures/pull/641>`_]
 * Add CLI command ``flexmeasures add report`` [see `PR #659 <https://www.github.com/FlexMeasures/flexmeasures/pull/659>`_]
 * Add CLI command ``flexmeasures show reporters`` [see `PR #686 <https://www.github.com/FlexMeasures/flexmeasures/pull/686>`_]
+* Add CLI command ``flexmeasures show schedulers`` [see `PR #708 <https://github.com/FlexMeasures/flexmeasures/pull/708>`_]
 
 Bugfixes
 -----------

diff --git a/documentation/cli/commands.rst b/documentation/cli/commands.rst
@@ -55,6 +55,7 @@ of which some are referred to in this documentation.
 ``flexmeasures show data-sources``                List available data sources.
 ``flexmeasures show beliefs``                     Plot time series data.
 ``flexmeasures show reporters``                   List available reporters.
+``flexmeasures show schedulers``                  List available schedulers.
 ================================================= =======================================
 
 

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
@@ -99,11 +103,12 @@ def create(  # noqa C901
 
     register_db_at(app)
 
-    # Register Reporters
+    # Register Reporters and Schedulers
     from flexmeasures.utils.coding_utils import get_classes_module
-    from flexmeasures.data.models.reporting import Reporter
+    from flexmeasures.data.models import reporting, planning
 
-    app.reporters = get_classes_module("flexmeasures.data.models.reporting", Reporter)
+    app.reporters = get_classes_module("flexmeasures.data.models", reporting.Reporter)
+    app.schedulers = get_classes_module("flexmeasures.data.models", planning.Scheduler)
 
     # add auth policy