Merge pull request #151 from Total-RD/ahalev_docs_v2

Docs

.gitignore

@@ -21,6 +21,7 @@ parts/
 sdist/
 var/
 wheels/
+docs/source/reference/api/
 pip-wheel-metadata/
 share/python-wheels/
 *.egg-info/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree: generated/
+
+   {% for item in methods %}
+       {% if item != "__init__" %}
+          ~{{ name }}.{{ item }}
+       {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree: generated/
+
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/conf.py

@@ -0,0 +1,68 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+import pymgrid
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'pymgrid'
+copyright = '2022, TotalEnergies'
+author = 'Avishai Halev'
+release = pymgrid.__version__
+version = pymgrid.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx.ext.autosummary',
+    # 'sphinx.ext.napoleon',
+    'sphinx.ext.doctest'
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'pydata_sphinx_theme'
+
+html_theme_options = {
+    "primary_sidebar_end": ["indices.html", "sidebar-ethical-ads.html"]
+}
+
+html_static_path = ['_static']
+
+
+def autodoc_skip_member(app, what, name, obj, skip, options):
+
+    if what != 'method':
+        return None
+
+    try:
+        exclusions = obj.__self__.__autodoc_exclusions__
+    except AttributeError: # not a method of an object, or object has no attribute '__autodoc_exclusions__'
+        return None
+
+    if name in exclusions:
+        return True
+
+    return None
+
+
+def setup(app):
+    app.connect('autodoc-skip-member', autodoc_skip_member)

docs/source/examples/index.rst

@@ -0,0 +1,4 @@
+Examples
+========
+
+This page is under development.

docs/source/getting_started.rst

@@ -0,0 +1,40 @@
+Getting Started
+===============
+
+.. _installation:
+
+Installation
+------------
+
+The easiest way to install *pymgrid* is with pip:
+
+.. code-block:: console
+
+    $ pip install -U pymgrid
+
+Alternatively, you can install from source. First clone the repo:
+
+.. code-block:: bash
+
+    $ git clone https://github.com/Total-RD/pymgrid.git
+
+Then navigate to the root directory of pymgrid and call
+
+.. code-block:: bash
+
+    $ pip install .
+
+Advanced Installation
+---------------------
+
+To use the included model predictive control algorithm <link> on microgrids containing gensets,
+additional dependencies are required as the optimization problem becomes mixed integer.
+
+The packages MOSEK and CVXOPT can both handle this case; you can install both by calling
+
+.. code-block:: bash
+
+    $ pip install pymgrid[genset_mpc]
+
+Note that MOSEK requires a license; see https://www.mosek.com/ for details.
+Academic and trial licenses are available.

docs/source/index.rst

@@ -0,0 +1,51 @@
+.. pymgrid documentation master file, created by
+   sphinx-quickstart on Sat Nov 19 12:49:18 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+*********************
+pymgrid documentation
+*********************
+
+**Version**: |version|
+
+*pymgrid* is a Python library to simulate tertiary control of electrical microgrids. *pymgrid* allows
+users to create and customize microgrids of their choosing. These microgrids can then be controlled using a user-defined
+algorithm or one of the control algorithms contained in *pymgrid*: rule-based control and model predictive control.
+
+Environments corresponding to the OpenAI-Gym API are also provided, with both continuous and discrete action space
+environments available. These environments can be used with your choice of reinforcement learning algorithm to train
+a control algorithm.
+
+*pymgrid* attempts to offer the simplest and most intuitive API possible, allowing the user to
+focus on their particular application.
+
+See the :doc:`getting_started` section for further information, including instructions on how to
+:ref:`install <installation>` the project.
+
+**Useful links**:
+`Binary Installers <https://pypi.org/project/pymgrid/>`__ |
+`Source Repository <https://github.com/Total-RD/pymgrid>`__
+
+
+.. note::
+
+   This project is under active development.
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 3
+
+   getting_started
+   reference/index
+   examples/index
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/reference/index.rst

@@ -0,0 +1,10 @@
+API reference
+=============
+
+This page contains an overview of all public *pymgrid* objects and functions.
+
+.. toctree::
+   :maxdepth: 2
+
+   microgrid
+   modules/index

docs/source/reference/microgrid.rst

@@ -0,0 +1,40 @@
+.. _api.microgrid:
+
+
+Microgrid
+=================
+
+.. currentmodule:: pymgrid
+
+Constructor
+-----------
+.. autosummary::
+    :toctree: api/microgrid/
+
+    Microgrid
+
+Methods
+-------
+.. autosummary::
+
+    :toctree: api/microgrid/
+
+    Microgrid.run
+    Microgrid.reset
+    Microgrid.sample_action
+    Microgrid.get_log
+    Microgrid.get_forecast_horizon
+    Microgrid.get_empty_action
+
+Serialization/IO/Conversion
+---------------------------
+.. autosummary::
+
+    :toctree: api/microgrid/
+
+    Microgrid.load
+    Microgrid.dump
+    Microgrid.from_nonmodular
+    Microgrid.from_scenario
+    Microgrid.serialize
+    Microgrid.to_nonmodular

docs/source/reference/modules/index.rst

@@ -0,0 +1,44 @@
+.. _api.modules:
+
+Modules
+=======
+
+.. currentmodule:: pymgrid.modules
+
+The modules defined here are commonly found in microgrids.
+Pass any combination of modules to :ref:`Microgrid <api.microgrid>` to define and run a microgrid.
+
+Timeseries Modules
+------------------
+
+Modules that are temporal in nature.
+
+
+
+.. autosummary::
+    :toctree: ../api/modules/
+
+    GridModule
+    LoadModule
+    RenewableModule
+
+Non-temporal Modules
+-------------
+
+Modules that do not depend on an underlying timeseries.
+
+.. autosummary::
+    :toctree: ../api/modules/
+
+    BatteryModule
+    GensetModule
+
+Helper Module
+--------------
+
+A module that cleans up after all the other modules are deployed.
+
+.. autosummary::
+    :toctree: ../api/modules/
+
+    UnbalancedEnergyModule

setup.py

@@ -11,7 +11,13 @@
 
 EXTRAS = dict()
 EXTRAS["genset_mpc"] = ["Mosek", "cvxopt"]
-EXTRAS["dev"] = ["pytest", "flake8", *EXTRAS["genset_mpc"]]
+EXTRAS["dev"] = [
+    "pytest",
+    "flake8",
+    "sphinx",
+    "pydata_sphinx_theme",
+    "numpydoc",
+    *EXTRAS["genset_mpc"]]
 EXTRAS["all"] = list(set(sum(EXTRAS.values(), [])))