Add API documentation. (#1108)

This patch adds the initial setup if the Python Sphinx Autodocs.

We use autosummary extension to generate recursively the tree of all
modules, classes and functions. Then we additionally add two pages
(actions.rst and pkgmanager.rst) to show the possibility to add custom
content to the autogenerated documentation.

To build the docs you need

python3-sphinx
python3-sphinx-autodoc-typehints

installed on the environment (via dnf or pip)

.gitignore

@@ -21,3 +21,5 @@ system_tests/vmdefs/centos*/.vagrant/
 TAGS
 .vscode/*
 !.vscode/extensions.json
+docs/build/*
+docs/source/_autosummary

convert2rhel/actions/__init__.py

@@ -174,8 +174,8 @@ class Convert2rhelLatest(Action):
         """
 
     #: Override dependencies with a Sequence that contains other
-    #: :class:`Action`s :attr:`Action.id`s that must be run before this one.
-    #: The :attr:`Action.id`s can be specified as string literals; you don't
+    #: :class:`Action`\ s :attr:`Action.id`\ s that must be run before this one.
+    #: The :attr:`Action.id`\ s can be specified as string literals; you don't
     #: have to import the class to reference them in the Sequence.
     dependencies = ()
 

docs/Makefile

@@ -0,0 +1,20 @@
+# 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     = source
+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
+
+# 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/source/_templates/custom-class-template.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/_templates/custom-module-template.rst

@@ -0,0 +1,69 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+
+.. rubric:: {{ _('Submodules') }}
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/source/actions.rst

@@ -0,0 +1,14 @@
+Actions
+#######
+
+Generic documentation TBA
+
+Actions API Docs
+----------------
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   convert2rhel.actions

docs/source/all.rst

@@ -0,0 +1,9 @@
+Complete API Docs
+=================
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   convert2rhel

docs/source/conf.py

@@ -0,0 +1,47 @@
+import sys
+
+
+project = "convert2rhel"
+copyright = "2024, Convert2RHEL Team"
+author = "Convert2RHEL Team"
+
+# -- Options for HTML output -------------------------------------------------
+# Adapted from https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion
+
+extensions = [
+    "sphinx.ext.autodoc",  # Core Sphinx library for auto html doc generation from docstrings
+    "sphinx.ext.autosummary",  # Create neat summary tables for modules/classes/methods etc
+    "sphinx.ext.intersphinx",  # Link to other project's documentation (see mapping below)
+    #    'sphinx.ext.linkcode',  # Add a link to the Python source code for classes, functions etc.
+    "sphinx_autodoc_typehints",  # Automatically document param types (less noise in class signature)
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
+
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+autoclass_content = "both"  # Add __init__ doc (ie. params) to class summaries
+html_show_sourcelink = False  # Remove 'view source code' from top of page (for html, not python)
+autodoc_inherit_docstrings = True  # If no docstring, inherit from base class
+set_type_checking_flag = True  # Enable 'expensive' imports for sphinx_autodoc_typehints
+add_module_names = False  # Remove namespaces from class/method signatures
+modindex_common_prefix = ["convert2rhel."]
+
+default_role = "code"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+exclude_patterns = []
+
+sys.path.append("../")
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "pyramid"
+html_theme_options = {
+    "sidebarwidth": "20%",
+}
+html_static_path = ["_static"]

docs/source/index.rst

@@ -0,0 +1,17 @@
+Welcome to convert2rhel Development Documentation
+=================================================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   all
+   meta
+   actions
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/meta.rst

@@ -0,0 +1,73 @@
+Documentation How-To
+====================
+
+The documentation has two inputs: docstrings in Python files of the
+``./convert2rhel/`` module and plain ReST markup in ``.rst`` files in
+``./docs/sources/*.rst``. Formatting rules for docstrings and rst
+files may be slightly different.
+
+Generally try to put information into docstrings including those at
+the module-level.
+
+Create additional rst files to describe generic concepts or anything
+which doesn't fit into the scope of a specific module.
+
+Layout
+------
+
+Rst files layout is currently very simple::
+
+  index.rst
+  -- all.rst          // Full API docs tree
+  -- meta.rst         // Documentation about documentation
+  -- actions.rst      // Dedicated page for a topic, can reference the API docs.
+
+How to build
+------------
+
+With a standard Fedora environment you need to install dependencies::
+
+  $ sudo dnf install python3-sphinx python3-sphinx-autodoc-typehints.noarchpython3-sphinx
+
+And then got to `./docs/` and run make::
+
+  $ make
+
+The output is going to appear in `./docs/build/html`.
+
+Tips & Tricks
+--------------
+
+References to modules, methods and classes
+..........................................
+
+To refer to a Python object use backticks.
+
+It can be a little tricky due to use the correct name for the object. See the following examples::
+
+   1. :mod:`actions`,     // works in docstrings, doesn't work in rst
+   2. :class:`Action`,    // works in docstrings, doesn't work in rst
+   3. :mod:`.actions`,    // looks fo all objects which end with the suffix `.actions`.
+                          // As it finds two: convert2rhel.actions and convert2rhel.unit_tests.actions
+                          // it takes the shortest of them
+   4. :mod:`convert2rhel.actions`,  // fully-qualified name
+   5. :mod:`~convert2rhel.unit_tests.actions`, // cuts the title to the last part
+   6. :attr:`.Action.id`,
+   7. :attr:`.Action.id`\ s, // see the note
+   8. `.actions`. // text in backticks recognized as inline code by default.
+
+Output:
+
+1. :mod:`actions`,
+2. :class:`Action`,
+3. :mod:`.actions`,
+4. :mod:`convert2rhel.actions`,
+5. :mod:`~convert2rhel.unit_tests.actions`,
+6. :attr:`.Action.id`,
+7. :attr:`.Action.id`\ s,
+8. `~convert2rhel.actions`.
+
+
+.. note:: ReST recognizes a closing backtick only if it is followed by
+   a space ot punctuation mark. If the backtick is followed by a
+   letter, insert the escaped space "`\\ \ `" after it.

docs/source/pkgmanager.rst

@@ -0,0 +1,10 @@
+Package Manager
+###############
+
+Generic documentation TBA
+
+Package Manager API Docs
+------------------------
+
+.. automodule:: convert2rhel.pkgmanager
+   :members: