equinor / ert

ERT - Ensemble based Reservoir Tool - is designed for running ensembles of dynamical models such as reservoir models, in order to do sensitivity analysis and data assimilation. ERT supports data assimilation using the Ensemble Smoother (ES), Ensemble Smoother with Multiple Data Assimilation (ES-MDA) and Iterative Ensemble Smoother (IES).
https://ert.readthedocs.io/en/latest/
GNU General Public License v3.0
98 stars 104 forks source link

Convert Ert to use mkdocs rather than sphinx #8014

Open pinkwah opened 1 month ago

pinkwah commented 1 month ago

Ert uses sphinx, which is a very broadly used documentation software. However, there are pain points, like slow build times, no live reload and use of ReStructured Text (subjective).

Instead, I would like to use mkdocs, which has the mkdocstring plugin that lets one easily document most everything in Python docstrings, with live reload. A notable user is Pydantic.

One difficulty is implementing documentation from Ert plugins, where it is provided at runtime and in RST format rather than mkdocs' Markdown.

dafeda commented 1 month ago

I don't have strong opinions on this but sphinx-autobuild can be used to get live reload as explained here:

https://github.com/equinor/ert/blob/main/CONTRIBUTING.md#build-documentation