DOCS: improved documentation using citet and citep for references, ma…

…kefiles for unix and windows to avoid having to use tox, use pydata theme rather than read the docs and improve docstrings for classes SIES and ES. Add badges for project 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,21 @@
 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 +34,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 +48,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,5 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,15 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:                                    <-- add at least this line
+   :private-members:
+   :show-inheritance:                           <-- plus I want to show inheritance...
+   :inherited-members:                          <-- ...and inherited members too
+
+   {% block methods %}
+   .. automethod:: __init__
+   {% endblock %}
+
+   .. rubric:: {{ _('Methods definition') }}

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,61 @@
+{{ 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-