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