feat: first commit that results in sucessful documentation build

ansys · Dec 4, 2024 · f6240ac · f6240ac
1 parent ce858d8
commit f6240ac
Show file tree

Hide file tree

Showing 4 changed files with 85 additions and 31 deletions.
diff --git a/.ci/build_doc.bat b/.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
diff --git a/doc/source/api/index.rst b/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>
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -62,8 +62,32 @@
         ignored_pattern += f"|{example_name}"
 ignored_pattern += "|11-server_types.py"
 ignored_pattern += "|06-distributed_stress_averaging.py"
+ignored_pattern += "|02-python_operators_with_dependencies.py"
+ignored_pattern += "|00-fluids_model.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.
@@ -77,16 +101,17 @@
     "enum_tools.autoenum",
     "nbsphinx",
     "sphinx.ext.autosectionlabel",
-    "sphinx.ext.autodoc",
+    #"sphinx.ext.autodoc",
     "sphinx.ext.graphviz",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
-    "sphinx_autodoc_typehints",
+    #"sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_gallery.gen_gallery",
     'sphinx_reredirects',
+    "ansys_sphinx_theme.extension.autoapi"
 ]
 
 redirects = {
@@ -107,7 +132,7 @@
 
 autosummary_generate = True
 
-autodoc_mock_imports = ["ansys.dpf.core.examples.python_plugins"]
+#autodoc_mock_imports = ["ansys.dpf.core.examples.python_plugins"]
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
@@ -189,7 +214,7 @@ def reset_servers(gallery_conf, fname, when):
     "reset_modules": (reset_servers,),
 }
 
-autodoc_member_order = "bysource"
+#autodoc_member_order = "bysource"
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -217,9 +242,36 @@ 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,
+        #"package_depth": 3,
+        "member_order": "bysource",
+    }
 }
 
-
+# Configuration for Sphinx autoapi
+suppress_warnings = [
+    "autoapi.python_import_resolution",
+    "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,

diff --git a/requirements/requirements_docs.txt b/requirements/requirements_docs.txt
@@ -1,4 +1,5 @@
 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