Add docs (#37)

.github/workflows/docs_build.yml

@@ -0,0 +1,35 @@
+name: docs (build)
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - .pre-commit-config.yaml
+      - .github/workflows/docs_build.yml
+      - '**.py'
+      - '**.ipynb'
+      - '**.js'
+      - '**.html'
+      - poetry.lock
+      - pyproject.toml
+      - '**.rst'
+      - '**.md'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+      - name: Install dependencies, build docs and coverage report
+        run: python3 -m pip install --upgrade pip && python3 -m pip install poetry
+      - uses: actions/[email protected]
+        with:
+          python-version: '3.10'
+          cache: 'poetry'
+      - run: |
+          python3 -m pip install --upgrade pip && python3 -m pip install poetry
+          poetry env use '3.10'
+          source $(poetry env info --path)/bin/activate
+          poetry install --with docs,test
+          cd docs && rm -rf source/reference/api && make html

.github/workflows/docs_deploy.yml

@@ -0,0 +1,45 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - .pre-commit-config.yaml
+      - .github/workflows/code_checks.yml
+      - .github/workflows/docs_build.yml
+      - .github/workflows/docs_deploy.yml
+      - .github/workflows/integration_tests.yml
+      - '**.py'
+      - '**.ipynb'
+      - '**.html'
+      - '**.js'
+      - poetry.lock
+      - pyproject.toml
+      - '**.rst'
+      - '**.md'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+        with:
+          submodules: 'true'
+      - name: Install dependencies, build docs and coverage report
+        run: python3 -m pip install --upgrade pip && python3 -m pip install poetry
+      - uses: actions/[email protected]
+        with:
+          python-version: '3.10'
+          cache: 'poetry'
+      - run: |
+          python3 -m pip install --upgrade pip && python3 -m pip install poetry
+          poetry env use '3.10'
+          source $(poetry env info --path)/bin/activate
+          poetry install --with docs,test
+          cd docs && rm -rf source/reference/api && make html
+      - name: Deploy to Github pages
+        uses: JamesIves/[email protected]
+        with:
+          branch: github_pages
+          folder: docs/build/html

.gitignore

@@ -56,7 +56,8 @@ coverage.xml
 *.pot
 
 # Sphinx documentation
-docs/_build/
+docs/build/
+docs/source/reference/api/
 
 # PyBuilder
 target/

README.md

@@ -108,7 +108,7 @@ One can add a path to `hydra.searchpath` either as a package (`pkg://path.to.con
 `path/to/config/directory/__init__.py` which is only interpreted when the config directory is added as a package.
 Hence, please refrain from using the `file://` notation.
 
-Hydra also allows for overriding configurations parameters from the command line. To see the available options and other information, run:
+Hydra also allows for overriding configuration parameters from the command line. To see the available options and other information, run:
 ```bash
 mmlearn_run 'hydra.searchpath=[pkg://path.to.config.directory]' +experiment=<name_of_experiment_yaml_file> --help
 ```

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/_static/custom.js

@@ -0,0 +1,6 @@
+requirejs.config({
+  paths: {
+    base: '/static/base',
+    plotly: 'https://cdn.plot.ly/plotly-2.30.0.min.js?noext',
+  },
+});

docs/source/_templates/base.html

@@ -0,0 +1,120 @@
+<!doctype html>
+<html class="no-js"{% if language is not none %} lang="{{ language }}"{% endif %}>
+  <head>
+    {%- block site_meta -%}
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width,initial-scale=1"/>
+    <meta name="color-scheme" content="light dark">
+    <meta name="google-site-verification" content="i0qQRaR9OA3tSz_9tDocdcXGY27Ox_cy4FrvTHD2C_0" />
+
+    {%- if metatags %}{{ metatags }}{% endif -%}
+
+    {# Make sure all pages have a description or Bing does not like us #}
+    {% if 'name="description"' not in metatags %}
+      <meta name="description" content="mmlearn Python API documentation">
+    {% endif %}
+
+    {%- block linktags %}
+        {%- if hasdoc('about') -%}
+          <link rel="author" title="{{ _('About these documents') }}" href="{{ pathto('about') }}" />
+        {%- endif -%}
+        {%- if hasdoc('genindex') -%}
+          <link rel="index" title="{{ _('Index') }}" href="{{ pathto('genindex') }}" />
+        {%- endif -%}
+        {%- if hasdoc('search') -%}
+          <link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}" />
+        {%- endif -%}
+        {%- if hasdoc('copyright') -%}
+          <link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}" />
+        {%- endif -%}
+        {%- if next -%}
+          <link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}" />
+        {%- endif -%}
+        {%- if prev -%}
+          <link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}" />
+        {%- endif -%}
+        {#- rel="canonical" (set by html_baseurl) -#}
+        {%- if pageurl %}
+        <link rel="canonical" href="{{ pageurl|e }}" />
+        {%- endif %}
+    {%- endblock linktags %}
+
+    {# Favicon #}
+    {%- if favicon_url -%}
+      <link rel="shortcut icon" href="{{ favicon_url }}"/>
+    {%- endif -%}
+
+    {#- Generator banner -#}
+    <meta name="generator" content="sphinx-{{ sphinx_version }}, furo {{ furo_version }}"/>
+
+    {# Bing webmasters meta tag #}
+    <meta name="msvalidate.01" content="8D2A5032F006424CAF54C0DDCD16F666" />
+
+    {%- endblock site_meta -%}
+
+    {#- Site title -#}
+    {%- block htmltitle -%}
+      {# See Sphinx monkey patch in conf.py #}
+      {% if 'title' in metas %}
+        <title>{{ metas.title }}</title>
+      {% elif not docstitle %}
+        <title>{{ title|striptags|e }}</title>
+      {% elif pagename == master_doc %}
+        <title>{{ docstitle|striptags|e }}</title>
+      {% else %}
+        <title>{{ title|striptags|e }} - {{ docstitle|striptags|e }}</title>
+      {% endif %}
+    {%- endblock -%}
+
+    {%- block styles -%}
+
+    {# Custom stylesheets #}
+    {%- block regular_styles -%}
+    {%- for css in css_files -%}
+      {% if css|attr("filename") -%}
+        {{ css_tag(css) }}
+      {%- else -%}
+        <link rel="stylesheet" href="{{ pathto(css, 1)|e }}" type="text/css" />
+      {%- endif %}
+    {% endfor -%}
+    {%- endblock regular_styles -%}
+
+    {#- Theme-related stylesheets -#}
+    {%- block theme_styles %}
+    {% include "partials/_head_css_variables.html" with context %}
+    {%- endblock -%}
+
+    {%- block extra_styles %}
+    {%- endblock -%}
+
+    {%- endblock styles -%}
+
+    {#- Custom front matter #}
+    {%- block extrahead -%}{%- endblock -%}
+
+    {# Custom JS #}
+    {%- block regular_scripts -%}
+    {% for path in script_files -%}
+      {{ js_tag(path) }}
+    {% endfor -%}
+    {%- endblock regular_scripts -%}
+
+    {# Theme-related JavaScript code #}
+    {%- block theme_scripts -%}
+    {%- endblock -%}
+
+    {# Footer icons #}
+    <script src="https://kit.fontawesome.com/2c1f516901.js" crossorigin="anonymous"></script>
+
+  </head>
+  <body>
+    {% block body %}
+    <script>
+      document.body.dataset.theme = localStorage.getItem("theme") || "auto";
+    </script>
+    {% endblock %}
+
+    {%- block scripts -%}
+    {%- endblock scripts -%}
+  </body>
+</html>

docs/source/_templates/custom-class-template.rst

@@ -0,0 +1,29 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __getitem__, __iter__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   {% for item in methods %}
+   .. automethod:: ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   {% for item in attributes %}
+   .. autoattribute:: ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/_templates/custom-module-template.rst

@@ -0,0 +1,60 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   {% for item in attributes %}
+   .. autodata:: {{ 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') }}
+
+   .. autosummary::
+      :toctree:
+         :hidden:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   {% for item in exceptions %}
+   .. autoexception:: {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}