Use Autoapi instead of Autodoc to generate Python docs in readthedocs

Autoapi uses a custom parser to read in the doc strings and doesn't need
to include the python modules.
This allows to generate the docs even without full build of the library,
we just need to run swig but there is no need to compile the library
with the swig layer to create working Python module.

This is only used in readthedocs because sphinx-autoapi is currenly not
packaged in fedora. However since in fedora we do regular full builds it
is not a problem and Autodoc can be used normally.

doc/conf.py.in

@@ -41,10 +41,31 @@ needs_sphinx = '4.1.2'
 extensions = [
     'breathe',
     'sphinx.ext.autodoc',
+    # Add autoapi extension only if running in readthedocs workflow, when running with cmake
+    # it gets replace by empty value because @AUTOAPI_EXTENSION@ is not defined.
+    # We use autoapi in readthedocs because it can parse code directly (code generated by swig)
+    # to access doc strings. The benefit is that we don't need to do a full build of the library
+    # to create working libdnf5 python module which is required by autodoc to get doc string.
+    # We can't use autoapi in our regular builds because it is not currently packaged in fedora,
+    # but this is not a problem because regular builds have access to the full working python
+    # module and can use autodoc normally.
+    @AUTOAPI_EXTENSION@
 ]
 breathe_projects = {'dnf5': '@CMAKE_CURRENT_BINARY_DIR@/xml/'}
 breathe_default_project = 'dnf5'
 
+# The autoapi config is only used doc/setup.py in readthedocs workflow (not by cmake)
+autoapi_type = 'python'
+autoapi_dirs = ['@CMAKE_CURRENT_BINARY_DIR@/../bindings/python3/libdnf5', '@CMAKE_CURRENT_BINARY_DIR@/../bindings/python3/libdnf5_cli']
+autoapi_root = "api/python/autoapi"
+autoapi_python_use_implicit_namespaces = True
+# We don't want to automatically generate the full documentation.
+# Instead we use directives, this allows greater control and both
+# cpp and python docs can have the same look and layout.
+autoapi_generate_api_docs = False
+autoapi_add_toctree_entry = False
+autoapi_add_objects_to_toctree = False
+
 if sphinx.version_info[:3] > (4, 0, 0):
     tags.add('sphinx4')
     extensions += ['dbusdoc']

doc/requirements.txt

@@ -1 +1,2 @@
 breathe
+sphinx-autoapi

doc/setup.py

@@ -39,7 +39,17 @@ def generate_bindings_from_dir(in_dir, out_dir):
 
 # configure the .in files
 configure("Doxyfile.in", "Doxyfile", {"@CMAKE_SOURCE_DIR@": os.path.join(DIR, "..")})
-configure("conf.py.in", "conf.py", {"@CMAKE_CURRENT_BINARY_DIR@": DIR})
+configure("conf.py.in", "conf.py", {"@CMAKE_CURRENT_BINARY_DIR@": DIR, "@AUTOAPI_EXTENSION@": "\'autoapi.extension\',"})
+
+# In place replace autodoc directives with autoapidoc directives.
+# Our readthedocs workflow uses autoapidoc instead of autodoc because
+# it is able to parse code generated by swig without including the
+# module -> therefore there is no need for a full build in order to
+# generate python docs.
+for in_file in os.listdir(os.path.join(DIR + "/api/python")):
+    if in_file.endswith(".rst"):
+        file = os.path.join("api/python/", in_file)
+        configure(file, file, {"autoclass": "autoapiclass"})
 
 
 # run doxygen manually