Bump sphinx from 7.1.0 to 8.1.3 in /requirements

.gitignore

@@ -192,3 +192,8 @@ src/ansys/grpc/
 
 # C extensions
 *.so
+
+# Ignore auto-generated API reference
+doc/source/api
+doc/source/examples
+doc/source/images/auto-generated

doc/source/conf.py

@@ -1,10 +1,10 @@
 import os
-import sys
 from glob import glob
 from datetime import datetime
 
 import numpy as np
 import pyvista
+import sphinx
 from ansys.dpf.core import __version__, server, server_factory
 from ansys.dpf.core.examples import get_example_required_minimum_dpf_version
 from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_light_mode, pyansys_logo_dark_mode
@@ -62,6 +62,9 @@
         ignored_pattern += f"|{example_name}"
 ignored_pattern += "|11-server_types.py"
 ignored_pattern += "|06-distributed_stress_averaging.py"
+# ignored_pattern += "|00-wrapping_numpy_capabilities.py"
+# ignored_pattern += "|01-package_python_operators.py"
+ignored_pattern += "|02-python_operators_with_dependencies.py"
 ignored_pattern += r")"
 
 # -- General configuration ---------------------------------------------------
@@ -155,7 +158,7 @@ def reset_servers(gallery_conf, fname, when):
         try:
             # check whether the process name matches
             if proc_name in proc.name():
-                # proc.kill()
+                proc.kill()
                 nb_procs += 1
         except psutil.NoSuchProcess:
             pass
@@ -323,3 +326,37 @@ def reset_servers(gallery_conf, fname, when):
 
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ["search.html"]
+
+
+def close_live_servers_and_processes(app: sphinx.application.Sphinx) -> None:
+    # Adapted from reset_servers() function, so this can be called after
+    # sphinx gallery finishes execution
+    import psutil
+    from ansys.dpf.core import server
+    import gc
+
+    gc.collect()
+    server.shutdown_all_session_servers()
+
+    proc_name = "Ans.Dpf.Grpc"
+    nb_procs = 0
+    for proc in psutil.process_iter():
+        try:
+            # check whether the process name matches
+            if proc_name in proc.name():
+                proc.kill()
+                nb_procs += 1
+        except psutil.NoSuchProcess:
+            pass
+
+def setup(app: sphinx.application.Sphinx) -> None:
+    """
+    Run hook function(s) during the documentation build.
+
+    Parameters
+    ----------
+    app : sphinx.application.Sphinx
+        Sphinx application instance containing the all the doc build configuration.
+    """
+
+    app.connect("builder-inited", close_live_servers_and_processes)

requirements/requirements_docs.txt

@@ -3,11 +3,12 @@ enum-tools[sphinx]==0.12.0
 graphviz==0.20.1
 imageio==2.36.0
 imageio-ffmpeg==0.5.1
+ipykernel==6.29.5
 nbsphinx==0.9.5
 pypandoc==1.14
 pytest-sphinx==0.6.3
 pyvista==0.44.2
-sphinx==7.1.0
+sphinx==8.1.3
 sphinx-copybutton==0.5.2
 sphinx-gallery==0.18.0
 sphinx-notfound-page==1.0.4

tox.ini

@@ -0,0 +1,89 @@
+[tox]
+description = Default tox environments list
+envlist =
+    code-style
+    doc-style-{linux,windows}
+    doc-{links,html,pdf}
+    dist
+skip_missing_interpreters = true
+isolated_build = true
+isolated_build_env = build
+
+[testenv]
+description = Checks for project testing with desired extras
+basepython =
+    test39: python3.9
+    test310: python3.10
+    test311: python3.11
+    test312: python3.12
+    {style,doc,dist}: python3
+passenv = 
+setenv =
+    PYTHONUNBUFFERED = yes
+deps =
+    -r{toxinidir}/requirements/requirements_test.txt
+commands =
+    pytest {toxinidir}/tests
+
+[testenv:code-style]
+description = Checks project code style
+skip_install = true
+deps =
+    pre-commit
+commands =
+    pre-commit install
+    pre-commit run --all-files --show-diff-on-failure
+
+[testenv:doc-style-{linux,windows}]
+description = Checks project documentation style
+skip_install = true
+allowlist_externals = 
+    find
+    vale
+    bash
+    cmd
+platform =
+    linux: linux
+    windows: win32
+commands =
+    linux: bash -c 'rst_files=$(find {toxinidir}/doc/source -type f -name "*.rst" ! -path "doc/source/api/*") && py_files=$(find {toxinidir}/examples -type f -name "*.py" ! -name "*_*") && vale_files="$rst_files $py_files" && vale sync --config="{toxinidir}/doc/.vale.ini" && vale --config="{toxinidir}/doc/.vale.ini" $rst_files'
+    windows: cmd /c "for /r {toxinidir}\doc\source %i in (*.rst) do @echo %i | findstr /v /i \doc\source\api\ > tmp_rst_files.txt"
+    windows: cmd /c "for /r {toxinidir}\examples %i in (*.py) do @echo %i | findstr /v /i *_* >> tmp_py_files.txt"
+    windows: cmd /c "setlocal enabledelayedexpansion && for /f %i in (tmp_rst_files.txt) do @set vale_files=!vale_files! %i && for /f %i in (tmp_py_files.txt) do @set vale_files=!vale_files! %i && vale sync --config="{toxinidir}\doc\.vale.ini" && vale --config="{toxinidir}\doc\.vale.ini" !rst_files! && endlocal"
+
+[testenv:doc-{clean,links,html,pdf}]
+description = Check if documentation generates properly
+allowlist_externals =
+    pdflatex
+passenv = 
+    ANSYSLMD_LICENSE_FILE
+setenv =
+    SOURCE_DIR = doc/source
+    BUILD_DIR = doc/_build
+    STATIC_DIR = doc/source/_static
+    SPHINX_APIDOC_OPTIONS=inherited-members
+    links: BUILDER = linkcheck
+    html: BUILDER = html
+    pdf: BUILDER = latex
+    links,html,pdf: BUILDER_OPTS = --color -v --keep-going
+deps = 
+    -r{toxinidir}/requirements/requirements_docs.txt 
+commands =
+    # Remove rendered documentation and additional static files
+    clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}"
+    clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:STATIC_DIR}/artifacts"
+
+    # Render documentation with desired builder
+    links,html,pdf: sphinx-apidoc -o {toxinidir}/doc/source/api {toxinidir}/src/ansys {toxinidir}/src/ansys/dpf/core/log.py \
+                        {toxinidir}/src/ansys/dpf/core/help.py {toxinidir}/src/ansys/dpf/core/mapping_types.py {toxinidir}/src/ansys/dpf/core/ipconfig.py \
+                        {toxinidir}/src/ansys/dpf/core/field_base.py {toxinidir}/src/ansys/dpf/core/cache.py {toxinidir}/src/ansys/dpf/core/misc.py \
+                        {toxinidir}/src/ansys/dpf/core/check_version.py {toxinidir}/src/ansys/dpf/core/operators/build.py {toxinidir}/src/ansys/dpf/core/operators/specification.py \
+                        {toxinidir}/src/ansys/dpf/core/vtk_helper.py {toxinidir}/src/ansys/dpf/core/label_space.py {toxinidir}/src/ansys/dpf/core/examples/python_plugins/* \
+                        {toxinidir}/src/ansys/dpf/core/examples/examples.py {toxinidir}/src/ansys/dpf/gate/* {toxinidir}/src/ansys/dpf/gatebin/* {toxinidir}/src/ansys/grpc/dpf/* \
+                         {toxinidir}/src/ansys/dpf/core/property_fields_container.py \
+                         -f --implicit-namespaces --separate  --no-headings
+    links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER}
+
+    # PDF documentation
+    pdf: pdflatex -interaction=nonstopmode -output-directory="{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {toxinidir}/{env:BUILD_DIR}/{env:BUILDER}/ansys-dpf-core.tex
+