diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 99415ae2d27..d1204b5c2f9 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -117,19 +117,25 @@ jobs: run: | choco install pandoc + - name: "Restore doc build cache" + id: cache-doc-build-restore + uses: actions/cache/restore@v4 + with: + path: | + doc/source/examples + # Cache key is composed of branch name, ansys version, hash of requirements_doc, + # and run_id to work around immutability + # We should also track version of pandoc, of graphviz, of packages installed by headless-display, and even of pydpf-core? + key: doc-build-${{ github.ref_name }}-DPF_${{inputs.ANSYS_VERSION}}${{inputs.standalone_suffix}}-${{hashfiles('requirements/requirements_docs.txt')}}-${{ github.run_id }} + restore-keys: | + doc-build-${{ github.ref_name }}-DPF_${{inputs.ANSYS_VERSION}}${{inputs.standalone_suffix}}-${{hashfiles('requirements/requirements_docs.txt')}}- + doc-build-master-DPF_${{inputs.ANSYS_VERSION}}${{inputs.standalone_suffix}}-${{hashfiles('requirements/requirements_docs.txt')}}- + - name: "Build HTML Documentation" shell: bash run: | tox -e doc-html --installpkg dist/${{ steps.wheel.outputs.wheel_name }} -x testenv:doc-html.setenv+='VIRTUALENV_SYSTEM_SITE_PACKAGES=true' - - name: "Retrieve package version" - shell: bash - run: | - echo "VERSION=$(python -c "from ansys.dpf.${{env.MODULE}} import __version__; print(__version__)")" >> GITHUB_OUTPUT - echo "${{env.PACKAGE_NAME}} version is: $(python -c "from ansys.dpf.${{env.MODULE}} import __version__; print(__version__)")" - id: version - if: always() - - name: "Upload Documentation Build log" uses: actions/upload-artifact@v4 with: @@ -137,6 +143,15 @@ jobs: path: doc/*.txt if: always() + - name: "Save doc-build cache" + id: cache-doc-build-save + uses: actions/cache/save@v4 + with: + path: | + doc/build + doc/source/examples + key: ${{ steps.cache-doc-build-restore.outputs.cache-primary-key }} + - name: "Zip HTML Documentation" shell: pwsh run: | diff --git a/doc/source/conf.py b/doc/source/conf.py index 7f6b77d4da1..5589e4a33a8 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,6 +1,7 @@ from datetime import datetime from glob import glob import os +import sys from pathlib import Path import subprocess @@ -16,6 +17,9 @@ from ansys.dpf.core import __version__, server, server_factory from ansys.dpf.core.examples import get_example_required_minimum_dpf_version +# Make sphinx_utilities modules importable +sys.path.append(os.path.join(os.path.dirname(__file__), "../sphinx_utilities")) + # Manage errors pyvista.set_error_output_file("errors.txt") # Ensure that offscreen rendering is used for docs generation @@ -56,12 +60,13 @@ server_version = server_instance.version server.shutdown_all_session_servers() print(f"DPF version: {server_version}") +print(f"DPF install: {server_instance.ansys_path}") # Build ignore pattern ignored_pattern = r"(ignore" header_flag = "\"\"\"" note_flag = r".. note::" -for example in glob(r"../../examples/**/*.py"): +for example in sorted(glob(r"../../examples/**/*.py")): minimum_version_str = get_example_required_minimum_dpf_version(example) if float(server_version) - float(minimum_version_str) < -0.05: example_name = example.split(os.path.sep)[-1] @@ -124,8 +129,7 @@ typehints_defaults = "comma" typehints_use_signature = True simplify_optional_unions = False -suppress_warnings = ['autosectionlabel.*'] - +autosectionlabel_prefix_document = True # Intersphinx mapping intersphinx_mapping = { "pyvista": ("https://docs.pyvista.org/", None), @@ -163,32 +167,6 @@ # -- Sphinx Gallery Options -from sphinx_gallery.sorting import FileNameSortKey - - -def reset_servers(gallery_conf, fname, when): - import gc - - import psutil - - from ansys.dpf.core import server - - 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} example {fname}.") - - sphinx_gallery_conf = { # convert rst to md for ipynb "pypandoc": True, @@ -205,7 +183,7 @@ def reset_servers(gallery_conf, fname, when): # Remove the "Download all examples" button from the top level gallery "download_all_examples": False, # Sort gallery example by file name instead of number of lines (default) - "within_subsection_order": FileNameSortKey, + "within_subsection_order": "FileNameSortKey", # directory where function granular galleries are stored "backreferences_dir": None, "image_scrapers": ("pyvista", "matplotlib"), @@ -213,7 +191,7 @@ def reset_servers(gallery_conf, fname, when): # "from pyvista import set_plot_theme\n" # "set_plot_theme('document')"), "reset_modules_order": 'both', - "reset_modules": (reset_servers,), + "reset_modules": ("reset_servers.reset_servers",), } @@ -272,6 +250,9 @@ def reset_servers(gallery_conf, fname, when): "design.grid", "config.cache", "design.fa-build", + "autosectionlabel.*", + "ref.python", + "toc.not_included" ] # Add any paths that contain custom static files (such as style sheets) here, @@ -405,4 +386,4 @@ def reset_servers(gallery_conf, fname, when): BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False if BUILD_EXAMPLES: - extensions.extend(["sphinx_gallery.gen_gallery"]) \ No newline at end of file + extensions.extend(["sphinx_gallery.gen_gallery"]) diff --git a/doc/sphinx_utilities/reset_servers.py b/doc/sphinx_utilities/reset_servers.py new file mode 100644 index 00000000000..1c754db0035 --- /dev/null +++ b/doc/sphinx_utilities/reset_servers.py @@ -0,0 +1,22 @@ +# +def reset_servers(gallery_conf, fname, when): + import gc + + import psutil + + from ansys.dpf.core import server + + 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} example {fname}.") diff --git a/requirements/requirements_docs.txt b/requirements/requirements_docs.txt index 604ca03b9b3..c4a1daeb137 100644 --- a/requirements/requirements_docs.txt +++ b/requirements/requirements_docs.txt @@ -1,4 +1,4 @@ -ansys-sphinx-theme[autoapi]==1.4.4 +ansys-sphinx-theme[autoapi]==1.5.3 enum-tools[sphinx]==0.13.0 graphviz==0.21 imageio==2.37.0 diff --git a/tox.ini b/tox.ini index c667f0ad42e..96aa9c5663d 100644 --- a/tox.ini +++ b/tox.ini @@ -227,7 +227,7 @@ commands = # Remove previously rendered documentation clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}" - # Clean files from previous build + # Clean examples from previous build clean: python -c "\ clean: from os.path import exists; import shutil; \ clean: [(shutil.rmtree(p) if exists(p) else None) for p in ['{env:SOURCE_DIR}/images/auto-generated']]; \