From f2158e7e2748798adbcae4c4465f81b3f50658d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ale=C5=A1=20Mat=C4=9Bj?= <amatej@redhat.com>
Date: Wed, 1 Feb 2023 16:20:23 +0100
Subject: [PATCH] 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       | 21 +++++++++++++++++++++
 doc/requirements.txt |  1 +
 doc/setup.py         | 12 +++++++++++-
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/doc/conf.py.in b/doc/conf.py.in
index 1a661e95c..0e0b619ed 100644
--- a/doc/conf.py.in
+++ b/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']
diff --git a/doc/requirements.txt b/doc/requirements.txt
index cd6467ed8..32089dc94 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1 +1,2 @@
 breathe
+sphinx-autoapi
diff --git a/doc/setup.py b/doc/setup.py
index facb05022..6747cab9c 100644
--- a/doc/setup.py
+++ b/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