Improve doc generation

.ci/build_doc.bat

@@ -3,10 +3,11 @@ call sphinx-apidoc -o ../docs/source/api ../ansys ../ansys/dpf/core/log.py ^
 ../ansys/dpf/core/help.py ../ansys/dpf/core/mapping_types.py ../ansys/dpf/core/ipconfig.py ^
 ../ansys/dpf/core/field_base.py ../ansys/dpf/core/cache.py ../ansys/dpf/core/misc.py ^
 ../ansys/dpf/core/check_version.py ../ansys/dpf/core/operators/build.py ../ansys/dpf/core/operators/specification.py ^
-../ansys/dpf/core/vtk_helper.py ../ansys/dpf/core/label_space.py ^
+../ansys/dpf/core/vtk_helper.py ../ansys/dpf/core/label_space.py ../ansys/dpf/core/examples/python_plugins/* ^
+../ansys/dpf/core/examples/examples.py ^
  -f --implicit-namespaces --separate  --no-headings
 pushd .
 cd ../docs/
 call make clean
-call make html
+call make html -v -v -v -P
 popd

.github/workflows/ci.yml

@@ -243,6 +243,10 @@ jobs:
       - name: "Setup Graphviz"
         uses: ts-graphviz/setup-graphviz@v1
 
+      - name: "Install OS packages"
+        run: |
+          choco install pandoc
+
       - name: "Install documentation packages for Python"
         run: |
           pip install -r requirements/requirements_docs.txt

docs/make.bat

@@ -11,6 +11,7 @@ set SOURCEDIR=source
 set BUILDDIR=build
 
 if "%1" == "" goto help
+if "%1" == "clean" goto clean
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -28,6 +29,30 @@ if errorlevel 9009 (
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
+:clean
+echo.Cleaning files form previous build...
+IF EXIST "build" (
+    rmdir "build" /s /q
+)
+IF EXIST "source\images\auto-generated" (
+    rmdir "source\images\auto-generated" /s /q
+)
+IF EXIST "source\examples\07-python-operators\plugins" (
+    robocopy "source\examples\07-python-operators\plugins" "source\_temp\plugins" /E >nul 2>&1
+)
+IF EXIST "source\examples" (
+    rmdir "source\examples" /s /q
+)
+IF EXIST "source\_temp\plugins" (
+    robocopy "source\_temp\plugins" "source\examples\07-python-operators\plugins" /E >nul 2>&1
+)
+IF EXIST "source\_temp" (
+    rmdir "source\_temp" /s /q
+)
+
+echo.Done.
+goto end
+
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 

docs/source/conf.py

@@ -67,6 +67,7 @@
 
 autosummary_generate = True
 
+autodoc_mock_imports = ["ansys.dpf.core.examples.python_plugins"]
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
@@ -85,7 +86,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -99,11 +100,35 @@
 # -- Sphinx Gallery Options
 from sphinx_gallery.sorting import FileNameSortKey
 
+
+def reset_servers(gallery_conf, fname, when):
+    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
+    print(f"Counted {nb_procs} {proc_name} processes {when} the example.")
+
+
 sphinx_gallery_conf = {
     # convert rst to md for ipynb
     "pypandoc": True,
     # path to your examples scripts
     "examples_dirs": ["../../examples"],
+    # abort build at first example error
+    'abort_on_example_error': True,
     # path where to save gallery generated examples
     "gallery_dirs": ["examples"],
     # Patter to search for example files
@@ -118,18 +143,24 @@
     # 'first_notebook_cell': ("%matplotlib inline\n"
     #                         "from pyvista import set_plot_theme\n"
     #                         "set_plot_theme('document')"),
+    "reset_modules_order": 'both',
+    "reset_modules": (reset_servers,),
 }
 
 autodoc_member_order = "bysource"
 
 
 # -- Options for HTML output -------------------------------------------------
+html_short_title = html_title = "PyDPF-Core"
 html_theme = "ansys_sphinx_theme"
 html_logo = pyansys_logo_black
 html_theme_options = {
-    "github_url": "https://github.com/pyansys/DPF-Core",
+    "github_url": "https://github.com/pyansys/pydpf-core",
     "show_prev_next": False,
-    "logo_link": "https://dpfdocs.pyansys.com/"  # navigate to the main page
+    "show_breadcrumbs": True,
+    "additional_breadcrumbs": [
+        ("PyAnsys", "https://docs.pyansys.com/"),
+    ],
 }
 
 

docs/source/user_guide/operators.rst

@@ -126,7 +126,7 @@ You can create data sources in two ways:
 
 
 Because several other examples use the ``Model`` class, this example uses the
-``DataSources``class:
+``DataSources`` class:
 
 .. code-block:: python
 
@@ -168,7 +168,7 @@ can also be connected to work on a temporal subset:
 
 Evaluate operators
 ~~~~~~~~~~~~~~~~~~
-With all the required inputs assigned, you can output the :class:`ansys.dpf.core.fields_container`_
+With all the required inputs assigned, you can output the :class:`ansys.dpf.core.fields_container`
 class from the operator:
 
 .. code-block:: python

examples/03-advanced/04-extrapolation_stress_3d.py

@@ -69,7 +69,7 @@
 ###############################################################################
 # Nodal stress result of integration points
 ###############################################################################
-# The MAPLD command ``ERESX,NO``is used to copy directly the
+# The MAPLD command ``ERESX,NO`` is used to copy directly the
 # Gaussian (integration) points results to the nodes, instead of the
 # results at nodes or elements (which are interpolation of results at a
 # few gauss points).

examples/03-advanced/05-extrapolation_strain_2d.py

@@ -53,7 +53,7 @@
 ###############################################################################
 # Extrapolate from integration points for elastic strain result
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# This example uses the ``gauss_to_node_fc``operator to compute nodal component
+# This example uses the ``gauss_to_node_fc`` operator to compute nodal component
 # elastic strain results from the elastic strain at the integration points.
 
 # Create elastic strain operator to get strain result of integration points

examples/03-advanced/10-asme_secviii_divtwo.py

@@ -41,7 +41,7 @@
 #
 # - ``alfasl`` = input("Introduce ``alfasl`` parameter from ASME\n")
 # - ``alfasl`` = float(alfasl)
-# -``m2`` = input("Introduce ``m2`` parameter from ASME\n")
+# - ``m2`` = input("Introduce ``m2`` parameter from ASME\n")
 # - ``m2`` = float(m2)
 #
 # For this exercise, ``alfasl`` = 2.2 and ``m2`` = .288, which is the same

examples/08-averaging/00-compute_and_average.py

@@ -146,8 +146,7 @@ def average_then_compute_von_mises(analysis):
 # Plot the results
 # ~~~~~~~~~~~~~~~~
 # Plot both von Mises stress fields side by side to compare them.
-# - The first plot displays the results when the equivalent stresses are calculated
-#   first.
+# - The first plot displays the results when the equivalent stresses are calculated first.
 # - The second plot shows the results when the averaging is done first.
 #
 

examples/08-averaging/README.txt

@@ -1,4 +1,4 @@
-.. _averaging_examples
+.. _averaging_examples:
 
 Averaging examples
 ==================