doc: use autoapi templates from ansys-sphinx-theme (#662)

Co-authored-by: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com>
Co-authored-by: Revathyvenugopal162 <revathy.venugopal@ansys.com>
Co-authored-by: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com>

Author: 3 people

.gitignore

@@ -76,7 +76,7 @@ instance/
 
 # Sphinx documentation
 doc/_build/
-doc/source/autoapi/
+doc/source/api/
 
 # PyBuilder
 .pybuilder/

doc/Makefile

@@ -22,7 +22,7 @@ help:
 # Customized clean due to examples gallery
 clean:
 	rm -rf $(BUILDDIR)/*
-	find . -type d -name "_autosummary" -exec rm -rf {} +
+	find . -type d -name "api" -exec rm -rf {} +
 
 # Create PDF
 pdf:

doc/make.bat

@@ -38,7 +38,7 @@ goto build-examples-py
 
 :clean
 rmdir /s /q %BUILDDIR% > /NUL 2>&1
-for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d"
+for /d /r %SOURCEDIR% %%d in (api) do @if exist "%%d" rmdir /s /q "%%d"
 goto end
 
 :help

doc/source/_autoapi_templates/index.rst

@@ -1,11 +1,13 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
 import os
+from pathlib import Path
 
 from ansys_sphinx_theme import (
     ansys_favicon,
     ansys_logo_white,
     ansys_logo_white_cropped,
+    get_autoapi_templates_dir_relative_path,
     get_version_match,
     latex,
     pyansys_logo_black,
@@ -63,18 +65,15 @@
 
 # Sphinx extensions
 extensions = [
-    "autoapi.extension",
-    "sphinx.ext.autodoc",
-    "sphinx_autodoc_typehints",
-    "sphinx.ext.autosummary",
-    "numpydoc",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "nbsphinx",
     "myst_parser",
     "jupyter_sphinx",
     "sphinx_design",
     "sphinx_jinja",
+    "autoapi.extension",
+    "numpydoc",
 ]
 
 # Intersphinx mapping
@@ -112,7 +111,6 @@
     # type, unless multiple values are being returned"
 }
 
-
 # static path
 html_static_path = ["_static"]
 
@@ -138,17 +136,19 @@
 # Configuration for Sphinx autoapi
 autoapi_type = "python"
 autoapi_dirs = ["../../src/ansys"]
+autoapi_root = "api"
 autoapi_options = [
     "members",
     "undoc-members",
     "show-inheritance",
     "show-module-summary",
     "special-members",
 ]
-autoapi_template_dir = "_autoapi_templates"
+autoapi_template_dir = get_autoapi_templates_dir_relative_path(Path(__file__))
 suppress_warnings = ["autoapi.python_import_resolution"]
-exclude_patterns = ["_autoapi_templates/index.rst"]
 autoapi_python_use_implicit_namespaces = True
+autoapi_keep_files = True
+autoapi_render_in_single_page = ["class", "enum", "exception"]
 
 # Examples gallery customization
 nbsphinx_execute = "always"
@@ -216,6 +216,7 @@
 ]
 
 # -- Declare the Jinja context -----------------------------------------------
+exclude_patterns = []
 BUILD_API = True if os.environ.get("BUILD_API", "true") == "true" else False
 if not BUILD_API:
     exclude_patterns.append("autoapi")
@@ -231,3 +232,17 @@
         "build_examples": BUILD_EXAMPLES,
     },
 }
+
+
+def prepare_jinja_env(jinja_env) -> None:
+    """
+    Customize the jinja env.
+
+    Notes
+    -----
+    See https://jinja.palletsprojects.com/en/3.0.x/api/#jinja2.Environment
+    """
+    jinja_env.globals["project_name"] = project
+
+
+autoapi_prepare_jinja_env = prepare_jinja_env

doc/source/conf.py

@@ -59,7 +59,7 @@ PyAnsys Geometry is a Python client library for the Ansys Geometry service.
                 and how to interact with them programmatically.
 
                 +++
-                .. button-link:: autoapi/index.html
+                .. button-link:: api/index.html
                    :color: secondary
                    :expand:
                    :outline:
@@ -117,7 +117,7 @@ PyAnsys Geometry is a Python client library for the Ansys Geometry service.
        getting_started/index
        user_guide/index
        {% if build_api %}
-       autoapi/index
+       api/index
        {% endif %}
        {% if build_examples %}
        examples

doc/source/index.rst

@@ -70,7 +70,7 @@ tests = [
     "vtk==9.2.6",
 ]
 doc = [
-    "ansys-sphinx-theme==0.10.6",
+    "ansys-sphinx-theme==0.11.0",
     "docker==6.1.3",
     "ipyvtklink==0.2.3",
     "jupyter_sphinx==0.4.0",
@@ -84,7 +84,7 @@ doc = [
     "pyvista[trame]==0.42.1",
     "requests==2.31.0",
     "sphinx==7.2.5",
-    "sphinx-autoapi==2.1.1",
+    "sphinx-autoapi @ git+https://github.com/jorgepiloto/sphinx-autoapi@feat/single-page-option",
     "sphinx-autodoc-typehints==1.24.0",
     "sphinx-copybutton==0.5.2",
     "sphinx_design==0.5.0",