fix: autoapi extension (#472)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Roberto Pastor Muela <[email protected]>

Author: 3 people

.gitignore

@@ -161,4 +161,4 @@ doc/source/_autosummary/
 doc/source/examples/gallery-examples/
 doc/source/sg_execution_times.rst
 # rendering of sphinx autoapi examples
-doc/source/examples/examples/
+doc/source/examples/api/

doc/Makefile

@@ -6,7 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
-AUTOAPI_OUTDIR = source/examples/examples
+AUTOAPI_OUTDIR = source/examples/api
 GALLERY_EXAMPLES = gallery-examples
 
 # Put it first so that "make" without argument is like "make help".

doc/changelog.d/472.fixed.md

@@ -0,0 +1 @@
+fix: autoapi extension

doc/make.bat

@@ -10,7 +10,7 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=_build
 set GALLERY_EXAMPLES=%SOURCEDIR%\examples\gallery-examples
-set AUTOAPI_OUTDIR=%SOURCEDIR%\examples\examples\
+set AUTOAPI_OUTDIR=%SOURCEDIR%\examples\api\
 
 if "%1" == "" goto help
 if "%1" == "pdf" goto pdf

doc/source/conf.py

@@ -69,9 +69,9 @@
     "ansys_sphinx_theme_autoapi": {
         "project": project,
         "directory": "src/ansys_sphinx_theme/examples",
-        "output": "examples/",
+        "output": "examples/api",
         "own_page_level": "function",
-        "add_toctree_entry": False,
+        "package_depth": 1,
     },
     "logo": "ansys",
 }
@@ -93,11 +93,9 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx_copybutton",
-    "sphinx_design",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx_gallery.gen_gallery",
-    "sphinx_jinja",
     "notfound.extension",
 ]
 

doc/source/examples/sphinx-autoapi.rst

@@ -7,6 +7,6 @@ This example shows how the Ansys Sphinx Theme renders API documentation using th
 
 .. toctree::
    :titlesonly:
-   :maxdepth: 5
+   :maxdepth: 1
 
-   <span class="nf nf-md-package"></span> The examples package<examples/index.rst>
+   api/index

doc/source/user-guide/autoapi.rst

@@ -27,6 +27,8 @@ and set the ``ansys_sphinx_theme_autoapi`` theme options in the ``html_theme_opt
 - ``ignore``: The list of directories to ignore. By default, this is empty.
 - ``add_toctree_entry``: If set to ``True``, the autoapi extension adds the generated files to the TOC tree.
   By default, this is set to ``False``.
+- ``package_depth``: The depth of the package. By default, this is set to ``3``. This is the ``namespace`` depth of the package.
+  For example, if the package is ``ansys``, the depth is ``1``. If the package is ``ansys.foo``, the depth is ``2``.
 
 All these options can be set in the ``conf.py`` file of your Sphinx project.
 
@@ -51,6 +53,7 @@ All these options can be set in the ``conf.py`` file of your Sphinx project.
             "class_content": "class",
             "ignore": [],
             "add_toctree_entry": False,
+            "package_depth": 3,
         }
     }
 

pyproject.toml

@@ -30,7 +30,7 @@ dependencies = [
 
 [project.optional-dependencies]
 autoapi = [
-    "sphinx-autoapi==3.1.1",
+    "sphinx-autoapi==3.2.1",
     "sphinx-design==0.6.1",
     "sphinx-jinja==2.0.2",
 ]

src/ansys_sphinx_theme/__init__.py

@@ -211,8 +211,8 @@ def fix_edit_html_page_context(
 
     Notes
     -----
-    .. [1] Originally implemented by `Alex Kaszynski <https://github.com/akaszynski>`_ in
-    `PyVista <https://github.com/pyvista/pyvista>`_,
+    [1] Originally implemented by `Alex Kaszynski <https://github.com/akaszynski>`_ in
+    `PyVista <https://github.com/pyvista/pyvista>`_ ,
     see https://github.com/pyvista/pyvista/pull/4113
     """
 
@@ -265,7 +265,7 @@ def fix_edit_link_page(link: str) -> str:
                     logging.debug(f"An error occurred: {e}")  # Log the exception as debug info
                     return link
 
-        elif pagename in ["autoapi", "api"]:
+        elif "api" in pagename:
             for obj_node in list(doctree.findall(addnodes.desc)):
                 domain = obj_node.get("domain")
                 if domain != "py":
@@ -275,7 +275,7 @@ def fix_edit_link_page(link: str) -> str:
                     if not isinstance(signode, addnodes.desc_signature):
                         continue
 
-                    fullname = signode["module"]
+                    fullname = signode["fullname"]
                     modname = fullname.replace(".", "/")
 
                     if github_source:

src/ansys_sphinx_theme/extension/autoapi.py

@@ -1,5 +1,3 @@
-"""Module for adding the autoapi extension with the theme."""
-
 # Copyright (C) 2021 - 2024 ANSYS, Inc. and/or its affiliates.
 # SPDX-License-Identifier: MIT
 #
@@ -44,12 +42,6 @@ def add_autoapi_theme_option(app: Sphinx) -> None:
     if not autoapi:
         return
 
-    # HACK: The ``sphinx_jinja`` and ``sphinx_design`` should be added to the extensions.
-    required_extensions = ["sphinx_jinja", "sphinx_design"]
-
-    for extension in required_extensions:
-        if extension not in app.config["extensions"]:
-            app.config["extensions"].append(extension)
     AUTOAPI_OPTIONS = [
         "members",
         "undoc-members",
@@ -68,6 +60,7 @@ def add_autoapi_theme_option(app: Sphinx) -> None:
     def prepare_jinja_env(jinja_env) -> None:
         """Prepare the Jinja environment for the theme."""
         jinja_env.globals["project_name"] = autoapi_project_name
+        jinja_env.globals["autoapi_depth"] = autoapi.get("package_depth", 3)
 
     # Set the autoapi options
 
@@ -104,8 +97,12 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     Dict[str, Any]
         A dictionary containing the version and parallel read/write safety flags.
     """
-    # HACK: The ``autoapi.extension`` should add here to initialize the extension.
-    app.setup_extension("autoapi.extension")
+    # HACK: The ``autoapi.extension``,  ``sphinx_design``, and ``sphinx_jinja`` extensions should be
+    # added to the Sphinx
+    required_extensions = ["sphinx_design", "sphinx_jinja", "autoapi.extension"]
+    for extension in required_extensions:
+        if extension not in app.config["extensions"]:
+            app.setup_extension(extension)
     app.connect("builder-inited", add_autoapi_theme_option, priority=400)
     return {
         "version": __version__,

src/ansys_sphinx_theme/theme/ansys_sphinx_theme/_templates/autoapi/index.rst

@@ -9,7 +9,8 @@ to interact with them programmatically.
    :maxdepth: 3
 
    {% for page in pages %}
-   {% if (page.top_level_object or page.name.split('.') | length == 3) and page.display %}
+   {% set length = autoapi_depth | int %}
+   {% if (page.top_level_object or page.name.split('.') | length == length) and page.display %}
    <span class="nf nf-md-package"></span> {{ page.name }}<{{ page.include_path }}>
    {% endif %}
    {% endfor %}