Improved documentation

* Use the modern pydata template (scipy/numpy) rather than rtd
* Include the readme in the doc for a nice rendering and avoid duplication
* Make links between the bibliography and the docstrings using the :cite: directive.
* Improved docstrings for SIES and ES
* Better API section
* Add badges in readme for better visibility

.gitignore

@@ -176,4 +176,7 @@ poetry.toml
 # LSP config files
 pyrightconfig.json
 
+# For the documentation
+_autosummary
+
 # End of https://www.toptal.com/developers/gitignore/api/python

README.md

@@ -1,8 +1,15 @@
 Iterative Ensemble Smoother
 ===========================
 
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://github.com/equinor/iterative_ensemble_smoother/blob/main/COPYING)
+[![Stars](https://img.shields.io/github/stars/equinor/iterative_ensemble_smoother.svg?style=social&label=Star&maxAge=2592000)](https://github.com/equinor/iterative_ensemble_smoother/stargazers)
+[![Python](https://img.shields.io/pypi/pyversions/iterative_ensemble_smoother.svg)](https://pypi.org/pypi/iterative_ensemble_smoother)
+[![PyPI](https://img.shields.io/pypi/v/iterative_ensemble_smoother.svg)](https://pypi.org/pypi/iterative_ensemble_smoother)
+[![Downloads](https://static.pepy.tech/badge/iterative_ensemble_smoother)](https://pepy.tech/project/iterative_ensemble_smoother)
+[![Build Status](https://github.com/equinor/iterative_ensemble_smoother/actions/workflows/upload_to_pypi.yml/badge.svg)](https://github.com/equinor/iterative_ensemble_smoother/actions/workflows/main.yml)
 [![Precommit: enabled](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![docs](https://readthedocs.org/projects/iterative_ensemble_smoother/badge/?version=latest&style=plastic)](https://iterative-ensemble-smoother.readthedocs.io/)
 
@@ -21,31 +28,9 @@ pip install iterative_ensemble_smoother
 
 ## Usage
 
-The following illustrates usage but does not actually create the inputs and can not be run.
+**iterative_ensemble_smoother** mainly implements `SIES` and `ESMDA` classes. Check out
+the examples section to see how to use them.
 
-The example below illustrates the usage of the package.
-Note that it does not create the necessary inputs and cannot be run directly.
-For complete information and runnable examples, please refer to [the documentation](http://iterative_ensemble_smoother.rtfd.io).
-
-```python
-import iterative_ensemble_smoother as ies
-
-# `prior` is a matrix of size (num_params, ensemble_size).
-# In geostatistical applications, it typically consists of Gaussian random fields
-# that model rock properties like porosities and permeabilities.
-
-# `response_ensemble` is a matrix of size (num_obs, ensemble_size) and is
-# generated by running a dynamical model, such as a flow simulator.
-# In geostatistical applications, this is typically a porous flow simulator like Eclipse or OPM flow.
-
-# `obs_errors` and `obs_values` are 1D array of size `num_obs` that hold observations from real-life
-# sensors and their uncertainty specifications.
-# In geostatistical applications, the observations are typically pressures, temperatures, production rates etc.
-
-smoother = ies.ES()
-smoother.fit(response_ensemble, obs_errors, obs_values)
-posterior = smoother.update(prior)
-```
 
 ## Building from source
 
@@ -57,7 +42,7 @@ cd iterative_ensemble_smoother
 pip install .
 ```
 
-### Building the documentation
+## Building the documentation
 
 ```bash
 apt install pandoc # Pandoc is required to build the documentation.

docs/source/_templates/autosummary/base.rst

@@ -0,0 +1,11 @@
+..
+   Template for the html base rendering
+
+   Modified from
+   https://github.com/sphinx-doc/sphinx/tree/master/sphinx/ext/autosummary/templates/autosummary/base.rst
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,21 @@
+..
+   Template for the html class rendering
+
+   Modified from
+   https://github.com/sphinx-doc/sphinx/tree/master/sphinx/ext/autosummary/templates/autosummary/class.rst
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :private-members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% block methods %}
+   .. automethod:: __init__
+   {% endblock %}
+
+   .. rubric:: {{ _('Methods definition') }}

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,67 @@
+..
+   Template for the html module rendering
+
+   Modified from
+   https://github.com/sphinx-doc/sphinx/tree/master/sphinx/ext/autosummary/templates/autosummary/module.rst
+
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      :template: class.rst
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/source/api.rst

@@ -1,10 +1,11 @@
-API reference
+.. _api_ref:
+
+=============
+API Reference
 =============
 
-.. currentmodule:: iterative_ensemble_smoother
+.. automodule:: iterative_ensemble_smoother
 
-.. autoclass:: iterative_ensemble_smoother.SIES
-   :members:
+.. raw:: latex
 
-.. autoclass:: iterative_ensemble_smoother.ESMDA
-   :members:
+    \clearpage

docs/source/bibliography.rst

@@ -2,3 +2,5 @@ Bibliography
 ============
 
 .. bibliography::
+   :all:
+   :labelprefix: Bib-

docs/source/conf.py

@@ -1,26 +1,168 @@
+"""
+iterative_ensemble_smoother documentation build configuration file.
+"""
+import datetime
+import os
+import re
+import sys
 from subprocess import check_output
 
+import iterative_ensemble_smoother as ies
+
+package_path = os.path.abspath("..")
+sys.path.insert(0, package_path)
+
 project = "iterative_ensemble_smoother"
-copyright = "2022, Equinor"
 author = "Equinor"
-release = "0.1.1"
-
+copyright = f"2022-{datetime.datetime.today().year}, {author}"
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+version = re.sub(r"\.dev.*$", r".dev", ies.__version__)
+release = version
 
+# convert the python file to a notebook
 check_output(["jupytext", "Polynomial.py", "-o", "Polynomial.ipynb"])
 
+# Do the same for this file
 check_output(["jupytext", "Oscillator.py", "-o", "Oscillator.ipynb"])
 
-
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
-    "nbsphinx",
+    "sphinx.ext.napoleon",  # autodoc understands numpy docstrings
+    "sphinx.ext.autodoc",  # Core library for html generation from docstrings
+    "sphinx.ext.autosummary",  # Create neat summary tables
+    "sphinx.ext.doctest",  # Test snippets in the documentation
+    "sphinx.ext.viewcode",  # Add links to highlighted source code
+    "sphinx.ext.intersphinx",  # Link to other projects’ documentation
+    "sphinx.ext.autosectionlabel",  # Allow reference sections using its title
+    # allows BibTeX citations to be inserted into documentation generated by Sphinx
     "sphinxcontrib.bibtex",
+    "jupyter_sphinx",
     "numpydoc",
+    "m2r2",  # compatibility with markdown
+    "myst_nb",  # to include jupyter notebooks
 ]
-bibtex_bibfiles = ["refs.bib"]
+
+# -----------------------------------------------------------------------------
+# Autosummary
+# -----------------------------------------------------------------------------
+
+# autosummaries from source-files
+autosummary_generate = True
+# dont show __init__ docstring
+autoclass_content = "class"
+# sort class members
+autodoc_member_order = "groupwise"
+# autodoc_member_order = 'bysource'
+
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+# This is because numpydoc screew up with autosummary
+# numpydoc_show_class_members=False
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = True
+napoleon_include_special_with_doc = False
+# napoleon_use_admonition_for_examples = False
+# napoleon_use_admonition_for_notes = False
+# napoleon_use_admonition_for_references = False
+napoleon_use_ivar = True
+# napoleon_use_param = True
+# napoleon_use_rtype = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# Add any external modules you want to refer to in the docs here.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = [".rst", ".md", ".ipynb"]
+
+# The encoding of source files.
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
 language = "en"
-html_theme = "sphinx_rtd_theme"
 
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ["build", "_templates/*.rst'", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# -----------------------------------------------------------------------------
+# HTML output
+# -----------------------------------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+# html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
+
+# TODO: when ies gets a nice logo
+# html_logo = '_static/logo.svg'
+# html_favicon = '_static/favicon.ico'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    # "google_analytics_id": "UA-140243896-1",
+    "show_prev_next": False,
+    "github_url": "https://github.com/equinor/iterative_ensemble_smoother",
+    "icon_links": [
+        {
+            "name": "Support",
+            "url": "https://github.com/equinor/iterative_ensemble_smoother/issues",
+            "icon": "fa fa-comment fa-fw",
+        },
+        # {
+        #     "name": "The Paper",
+        #     "url": "https://doi.org/10.21105/joss.01450",
+        #     "icon": "fa fa-file-text fa-fw",
+        # },
+    ],
+}
+
+# Title displayed on the html page
+html_title = "Iterative Ensemble Smoother"
+
+# -----------------------------------------------------------------------------
+# Bibliography
+# -----------------------------------------------------------------------------
+
+bibtex_bibfiles = ["./refs.bib"]
+bibtex_default_style = "unsrt"
+bibtex_reference_style = "author_year"
+suppress_warnings = ["bibtex.duplicate_citation", "autosectionlabel.*"]
 
 numpydoc_class_members_toctree = False
+
+# -----------------------------------------------------------------------------
+# Myst configuration
+# -----------------------------------------------------------------------------
+
+# see https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-mathjax
+# for math parsing in jupyter notebooks
+myst_enable_extensions = [
+    "amsmath",
+    "dollarmath",
+]

docs/source/examples.rst

@@ -7,3 +7,5 @@ Example Usage
 
    Polynomial
    Oscillator
+
+* :ref:`genindex`

docs/source/glossary.rst

@@ -17,8 +17,8 @@ Glossary
 
     forward model
          A forward model maps model parameters to predicted measurements
-         (:term:`prediction`). See, for instance, :cite:`evensen2018analysis` and
-         :cite:`evensen2019efficient`.
+         (:term:`prediction`). See, for instance, :cite:t:`evensen2018analysis` and
+         :cite:t:`evensen2019efficient`.
 
     error function
         The error function, or erf_, is a function that for a