Autogenerate API documentation

[ReimarBauer]

We should add into the CI workflow an API documentation workflow and additional publish the released and develop API

with calling pdoc3 mslib --html I found the problems

• https://github.com/Open-MSS/MSS/issues/2502
• https://github.com/Open-MSS/MSS/issues/2503
• https://github.com/Open-MSS/MSS/issues/2504

There is also maybe another one, which I have not tracked down, on the call a

ImportWarning: Working outside of application context. shows up

pdoc3 --skip-errors mslib --html can be used to look on the content

[matrss]

Some questions:

Who is the target audience for this API documentation?

What even is the API of mslib? How is it used in other projects?

Do we have a clearly defined API, or is it a "everything goes" situation as of now? (i.e. is everything not marked as private deliberately public, or not?)

Why pull in pdoc3, when sphinx should already be capable of doing this?

[ReimarBauer]

1. next gsoc students and those who want to contribute.
2. und 3. current situation. dependent on the tool we use, we can highlight some parts.

viertens. I do not insist on pydoc3, but I want a similiar functionality that on each build we see if some of the modules are broken, where we don't have tests

[matrss]

I do not insist on pydoc3

OK, now you have to clarify. pdoc3 and pydoc3 are two different things. pydoc3 is part of python, pdoc3 is a third-party project.

[ReimarBauer]

I do not insist on which we use. Sometimes typos happen...

[matrss]

This is starting point using sphinx' builtin tools to generate such an API reference:

diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 00000000..c425816e
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,8 @@
+API
+===
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   mslib
diff --git a/docs/conf.py b/docs/conf.py
index 80e5e185..9cc9aae9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -117,7 +117,14 @@ on_rtd = os.environ.get('READTHEDOCS') == 'True'
 # 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_rtd_theme', 'sphinxcontrib.video']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx_rtd_theme',
+    'sphinxcontrib.video',
+]
+
+autosummary_generate = True

 # raise a warning when a secondary source is missing.
 video_enforce_extra_source = True
diff --git a/docs/index.rst b/docs/index.rst
index 02af2912..ddd49e98 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -40,6 +40,7 @@ Topics
    authors
    tutorial
    gallery/index
+   api


 Indices and tables

For some reason it doesn't generate pages for classes and class members though, as reported here: https://github.com/sphinx-doc/sphinx/issues/7912. Some template changes would be required to achieve that.