doc: use sphinx-autoapi for API reference (#1952)

* feat: first commit that results in sucessful documentation build

* feat: bumped sphinx version manually to 8.1.3

* feat: cleaned up conf.py

* doc: sphinx 7.4.7 works for autoapi

* fix: ci doc build resulting in error

* fix: check if modifying action file fixes doc-build error

* fix: quick test

* fix: trialing another fix

* fix: modified docs.yml file

* doc: todo to address warnings that are being suppressed

* fix: duplicated dependency

---------

Co-authored-by: Jorge Martínez <[email protected]>

Author: moe-ad

.ci/build_doc.bat

@@ -1,28 +1,28 @@
-set SPHINX_APIDOC_OPTIONS=inherited-members
-call sphinx-apidoc -o ../doc/source/api ../src/ansys ../src/ansys/dpf/core/log.py ^
-../src/ansys/dpf/core/help.py ../src/ansys/dpf/core/mapping_types.py ../src/ansys/dpf/core/ipconfig.py ^
-../src/ansys/dpf/core/field_base.py ../src/ansys/dpf/core/cache.py ../src/ansys/dpf/core/misc.py ^
-../src/ansys/dpf/core/check_version.py ../src/ansys/dpf/core/operators/build.py ../src/ansys/dpf/core/operators/specification.py ^
-../src/ansys/dpf/core/vtk_helper.py ../src/ansys/dpf/core/label_space.py ../src/ansys/dpf/core/examples/python_plugins/* ^
-../src/ansys/dpf/core/examples/examples.py ../src/ansys/dpf/gate/* ../src/ansys/dpf/gatebin/* ../src/ansys/grpc/dpf/* ^
- ../src/ansys/dpf/core/property_fields_container.py ^
- -f --implicit-namespaces --separate  --no-headings
+@echo off
+
+REM Move to the documentation directory
 pushd .
 cd ../doc/
+
+REM Clean the previous build
 call make clean
+
+REM Build the HTML documentation
 call make html -v -v -v -P
 
+REM Display the directory contents for verification
 dir
 
-rem Patch pyVista issue with elemental plots
+REM Patch pyVista issue with elemental plots by copying necessary images
+xcopy source\examples\04-advanced\02-volume_averaged_stress\sphx_glr_02-volume_averaged_stress_001.png build\html\_images\ /y /f
+xcopy source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_001.png build\html\_images\ /y /f
+xcopy source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_002.png build\html\_images\ /y /f
+xcopy source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_003.png build\html\_images\ /y /f
+xcopy source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_004.png build\html\_images\ /y /f
+xcopy source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_005.png build\html\_images\ /y /f
+xcopy source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_006.png build\html\_images\ /y /f
+xcopy source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_007.png build\html\_images\ /y /f
+xcopy source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_thumb.png build\html\_images\ /y /f
 
-xcopy  source\examples\04-advanced\02-volume_averaged_stress\sphx_glr_02-volume_averaged_stress_001.png   build\html\_images\  /y /f
-xcopy  source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_001.png                     build\html\_images\  /y /f
-xcopy  source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_002.png                     build\html\_images\  /y /f
-xcopy  source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_003.png                     build\html\_images\  /y /f
-xcopy  source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_004.png                     build\html\_images\  /y /f
-xcopy  source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_005.png                     build\html\_images\  /y /f
-xcopy  source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_006.png                     build\html\_images\  /y /f
-xcopy  source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_007.png                     build\html\_images\  /y /f
-xcopy  source\examples\12-fluids\02-fluids_results\sphx_glr_02-fluids_results_thumb.png                   build\html\_images\  /y /f
+REM Return to the original directory
 popd

.github/workflows/docs.yml

@@ -73,17 +73,33 @@ jobs:
         with:
           python-version: ${{ inputs.python_version }}
 
+      - name: "Create virtual environment in the current workspace"
+        shell: pwsh
+        run: python -m venv .venv --system-site-packages
+      
+      - name: "Update PATH for virtual environment"
+        run: |
+          echo "${{ github.workspace }}\.venv\Scripts" >> $env:GITHUB_PATH
+
+      - name: "Update pip to the latest version"
+        shell: pwsh
+        run: |
+          python -m pip install -U pip
+
       - name: "Install requirements"
-        run: pip install -r requirements/requirements_build.txt
+        shell: pwsh
+        run: |
+          python -m pip install -r requirements/requirements_build.txt
 
       - name: "Build the wheel"
-        shell: bash
+        shell: pwsh
         run: |
-          if [ ${{ matrix.os }} == "ubuntu-latest" ]; then
-              export platform="manylinux_2_17"
-          else
-              export platform="win"
-          fi
+          $os = "${{ matrix.os }}"
+          if ($os -eq "ubuntu-latest") {
+              $platform = "manylinux_2_17"
+          } else {
+              $platform = "win"
+          }
           python .ci/build_wheel.py -p $platform -w
 
       - name: "Expose the wheel"
@@ -96,9 +112,9 @@ jobs:
           echo "wheel_name=${name[0]}" >> $GITHUB_OUTPUT
 
       - name: "Install package wheel"
-        shell: bash
+        shell: pwsh
         run: |
-          pip install dist/${{ steps.wheel.outputs.wheel_name }}[plotting]
+          python -m pip install dist/${{ steps.wheel.outputs.wheel_name }}[plotting]
 
       - name: "Install DPF"
         id: set-server-path
@@ -112,9 +128,10 @@ jobs:
         uses: ansys/pydpf-actions/[email protected]
 
       - name: "Test import"
-        shell: bash
+        shell: pwsh
         working-directory: tests
-        run: python -c "from ansys.dpf import core"
+        run: |
+          python -c "from ansys.dpf import core"
 
       - name: "Setup headless display"
         uses: pyvista/setup-headless-display-action@v2
@@ -127,20 +144,23 @@ jobs:
           choco install pandoc
 
       - name: "Install documentation packages for Python"
+        shell: pwsh
         run: |
-          pip install -r requirements/requirements_docs.txt
+          python -m pip install -r requirements/requirements_docs.txt
 
       - name: "Kill all servers"
         uses: ansys/pydpf-actions/[email protected]
 
       - name: "Ensure VTK compatibility"
+        shell: pwsh
         run: |
           python -m pip uninstall --yes vtk
           python -m pip install --extra-index-url https://wheels.vtk.org vtk-osmesa==${{ env.VTK_OSMESA_VERSION }}
 
       - name: "List installed packages"
-        shell: bash
-        run: pip list
+        shell: pwsh
+        run: |
+          python -m pip list
 
       - name: "Build HTML Documentation"
         shell: cmd /D /E:ON /V:OFF /C "CALL "{0}""

doc/source/api/index.rst

@@ -1,10 +1,11 @@
-.. _ref_api_section:
-
-=============
 API reference
 =============
+
+This section describes PyDPF-Core endpoints, their capabilities, and how
+to interact with them programmatically.
+
 .. toctree::
-   :maxdepth: 2
-   :caption: API reference
-   
-   ansys.dpf.core
+   :titlesonly:
+   :maxdepth: 3
+
+   <span class="nf nf-md-package"></span> ansys.dpf.core</api/ansys/dpf/core/index>

doc/source/conf.py

@@ -64,6 +64,28 @@
 ignored_pattern += "|06-distributed_stress_averaging.py"
 ignored_pattern += r")"
 
+# Autoapi ignore pattern
+autoapi_ignore_list = [
+    "*/log.py",
+    "*/help.py",
+    "*/mapping_types.py",
+    "*/ipconfig.py",
+    "*/field_base.py",
+    "*/cache.py",
+    "*/misc.py",
+    "*/check_version.py",
+    "*/operators/build.py",
+    "*/operators/specification.py",
+    "*/vtk_helper.py",
+    "*/label_space.py",
+    "*/examples/python_plugins/*",
+    "*/examples/examples.py",
+    "*/gate/*",
+    "*/gatebin/*",
+    "*/grpc/*",
+    "*/property_fields_container.py"
+]
+
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -75,18 +97,16 @@
 # ones.
 extensions = [
     "enum_tools.autoenum",
-    "nbsphinx",
     "sphinx.ext.autosectionlabel",
-    "sphinx.ext.autodoc",
     "sphinx.ext.graphviz",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
-    "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_gallery.gen_gallery",
     'sphinx_reredirects',
+    "ansys_sphinx_theme.extension.autoapi",
 ]
 
 redirects = {
@@ -105,9 +125,8 @@
     "pyvista": ("https://docs.pyvista.org/", None),
 }
 
-autosummary_generate = True
+autosummary_generate = False
 
-autodoc_mock_imports = ["ansys.dpf.core.examples.python_plugins"]
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
@@ -189,8 +208,6 @@ def reset_servers(gallery_conf, fname, when):
     "reset_modules": (reset_servers,),
 }
 
-autodoc_member_order = "bysource"
-
 
 # -- Options for HTML output -------------------------------------------------
 html_short_title = html_title = "PyDPF-Core"
@@ -217,9 +234,35 @@ def reset_servers(gallery_conf, fname, when):
         "min_chars_for_search": 2,
         "ignoreLocation": True,
     },
+    "ansys_sphinx_theme_autoapi": {
+        "project": project,
+        "output": "api",
+        "directory": "src/ansys",
+        "use_implicit_namespaces": True,
+        "keep_files": True,
+        "own_page_level": "class",
+        "type": "python",
+        "options": [
+            "members",
+            "undoc-members",
+            "show-inheritance",
+            "show-module-summary",
+            "special-members",
+        ],
+        "class_content": "class",
+        "ignore": autoapi_ignore_list,
+        "add_toctree_entry": True,
+        "member_order": "bysource",
+    }
 }
 
-
+# Configuration for Sphinx autoapi
+suppress_warnings = [
+    "autoapi.python_import_resolution", # Todo: remove suppression of this warning in the future
+    "design.grid",
+    "config.cache",
+    "design.fa-build",
+]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

requirements/requirements_docs.txt

@@ -1,4 +1,4 @@
-ansys-sphinx-theme==1.2.2
+ansys-sphinx-theme[autoapi]==1.2.2
 enum-tools[sphinx]==0.12.0
 graphviz==0.20.1
 imageio==2.36.0
@@ -7,7 +7,7 @@ nbsphinx==0.9.5
 pypandoc==1.14
 pytest-sphinx==0.6.3
 pyvista==0.44.2
-sphinx==7.1.0
+sphinx==7.4.7
 sphinx-copybutton==0.5.2
 sphinx-gallery==0.18.0
 sphinx-notfound-page==1.0.4