Add preliminary version of the documentation

Makefile

@@ -53,6 +53,11 @@ build:
 	@echo "Building package"
 	poetry build
 
+build-docs:
+	@echo "Building docs"
+	poetry run m2r README.md --overwrite
+	cd ./docs && make html
+
 publish:
 	@echo "Publishing package"
 	poetry publish

README.rst

@@ -0,0 +1,71 @@
+
+
+.. raw:: html
+
+   <div align="center">
+       <img src="res/ontime-logo.png" width="180" title="hover text">
+       <h1>onTime—<i>your library to work with time series</i></h1>
+   </div>
+
+
+
+.. image:: https://github.com/fredmontet/ontime/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/fredmontet/ontime/actions/workflows/ci.yml
+   :alt: Continuous Integration
+
+
+.. image:: https://badge.fury.io/py/ontime.svg
+   :target: https://badge.fury.io/py/ontime
+   :alt: PyPI version
+
+
+Getting Started
+---------------
+
+For now, the best is to look at the examples in the ``notebooks`` folder.
+
+Purpose of the library
+----------------------
+
+The purpose of onTime is to make a technological transfer to the partners of the 
+DiagnoBat project with respect to their intellectual property. Most parts of 
+the library are extendable by using dynamically loaded classes. This
+mecanism allows anyone to keep parts of the library private within their own company. 
+
+The library objectives are :
+
+
+#. to extend the time series libraries (Darts, GluonTS, Kats, etc.)
+#. to provide benchmarking tools for models and/or detectors
+#. to provide domain specific tools (e.g. for energy consumption, district heating networks, etc.)
+
+In case you have any questions, don't hesitate to ask them by opening an issue or email.
+
+Contribute
+----------
+
+We welcome contributions to onTime. If you want to contribute code, please open an issue first or assign 
+yourself to one.
+
+As of the 15th of January 2024, since the project is small, we add ourselves to the repository as
+contributors and we don't use pull requests. We will use pull requests when the project will be bigger.
+
+Still, please respect the following branch naming convention : 
+
+.. code-block::
+
+   <issue number>-<issue slug>
+
+
+For example, if you are working on issue #1, you should create a branch named ``1-add-readme``. If you are
+on an issue page, there is a button to create a branch with the correct name in the sidebar.
+
+Authors
+-------
+
+Frédéric Montet ([email protected])
+
+License
+-------
+
+Apache License 2.0

docs/Makefile

@@ -0,0 +1,26 @@
+# 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     = .
+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
+
+open:
+	@open "$(BUILDDIR)/html/index.html"
+
+del:
+	rm -rf "$(BUILDDIR)"
+
+# 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/conf.py

@@ -0,0 +1,80 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../src/ontime'))
+print(sys.path[0])
+
+# -- Project information -----------------------------------------------------
+
+project = 'onTime'
+copyright = '2024, onTime development team'
+author = 'Frédéric Montet'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'nbsphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.coverage',
+    'sphinx.ext.napoleon',
+    'recommonmark'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# 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']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "pydata_sphinx_theme"
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- NB Sphinx configuration --------------------------------------------------
+
+nbsphinx_allow_errors = True
+
+# -- Autosummary configuration ------------------------------------------------
+
+autosummary_generate = True
+
+# -- Pydata Sphinx Theme configuration ----------------------------------------
+
+html_logo = "_static/logo-inline.png"
+html_theme_options = {
+    "github_url": "https://github.com/fredmontet/ontime",
+    "external_links": [
+        {"name": "Releases", "url": "https://github.com/fredmontet/ontime/releases"},
+    ],
+    "show_prev_next": True
+}
+

docs/contributing/contribution_guidelines.rst

@@ -0,0 +1,48 @@
+Contribution guidelines
+=======================
+
+We are happy to welcome you as a contributor to the onTime project. This guide presents the
+contribution workflow and some guidelines to help you to get started.
+
+
+Contributing to the code
+------------------------
+
+If you want to contribute code, please open an issue first or assign yourself to one. The 
+issue board here_, it's always nice to check if what you want to do is already corresponding
+to an issue.
+
+
+Branching model
+---------------
+
+As of the 15th of January 2024, since the project is small, we add ourselves to the repository as
+contributors and we don't use pull requests. We will use pull requests when the project will be bigger.
+
+Still, please respect the following branch naming convention : 
+
+    <issue number>-<issue slug>
+
+For example, if you are working on issue #1, you should create a branch named `1-add-readme`. If you are
+on an issue page, there is a button to create a branch with the correct name in the sidebar.
+
+
+Submit bug reports
+------------------
+
+To submit a bug report, please provide us with a
+comprehensive issue comment allowing us to reproduce the error.
+
+In case the bug can be reproduced in a notebook, a link to a notebook executed
+on a tool like Binder_ is perfect.
+
+
+Submit enhancements and feature requests
+---------------------------------
+
+To suggest enhancement or feature, the usual way is to make an issue. If you
+want to discuss with us live, please contact us.
+
+
+.. _here: https://github.com/fredmontet/ontime/issues
+.. _Binder: https://mybinder.org/

docs/contributing/index.rst

@@ -0,0 +1,11 @@
+Contributing
+============
+
+As always in open source projects, contributions are very welcome. Here are a
+few document to explain the way we work, how to make a release and what we plan
+to do next.
+
+.. toctree::
+
+    contribution_guidelines
+    make_a_release

docs/contributing/make_a_release.rst

@@ -0,0 +1,71 @@
+.. image:: https://github.com/fredmontet/ontime/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/fredmontet/ontime/actions/workflows/ci.yml
+   :alt: Continuous Integration
+
+
+.. image:: https://badge.fury.io/py/ontime.svg
+   :target: https://badge.fury.io/py/ontime
+   :alt: PyPI version
+
+==============
+Make a Release
+==============
+
+This is a guides to publish onTime on PyPI.
+
+#. Change branch to `main`
+
+    .. code-block:: bash
+
+        # make sure you are on the right branch
+        git checkout main
+
+#. Merge `develop` on `main`
+
+    .. code-block:: bash
+
+        git merge develop
+        git push
+
+#. Update the version in `pyproject.toml`
+
+    .. code-block:: bash
+
+        [tool.poetry]
+        name = "ontime"
+        version = "x.y.z-suffix"
+
+#. Commit and push
+
+    .. code-block:: bash
+
+        git add pyproject.toml
+        git commit -m 'Update version to x.y.z-suffix'
+
+#. Tag the version
+
+    .. code-block:: bash
+    
+        git tag -a v<x.y.z-suffix> -m 'Version x.y.z-suffix'
+        git push origin v<x.y.z-suffix>
+
+#. Build the package
+
+    .. code-block:: bash
+
+        make build
+
+#. Publish the package
+
+    .. code-block:: bash
+
+        make publish
+
+    Also, make the `GitHub Release <https://github.com/fredmontet/ontime/releases/new>`_.
+
+#. Check if everything went well
+
+    * On `GitHub Actions <https://github.com/fredmontet/ontime/actions>`_.
+    * On `PyPI <https://pypi.org/project/ontime/>`_.
+    * Done! 🎉
+