diff --git a/.ci/build_doc.bat b/.ci/build_doc.bat index f5a447971d..2a5d1e90ad 100644 --- 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/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2ba37ecbe1..c1fab71c7d 100644 --- a/.github/workflows/docs.yml +++ b/.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/check-licenses@v2.3 - 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/kill-dpf-servers@v2.3 - 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}"" diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index 2591e619ba..84a8a29d1c 100644 --- 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 + + ansys.dpf.core diff --git a/doc/source/conf.py b/doc/source/conf.py index 7390890e9c..e7f9775035 100644 --- a/doc/source/conf.py +++ b/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", + "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 index 9906654e9e..3f937a6703 100644 --- 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 @@ -7,7 +8,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 diff --git a/src/ansys/dpf/core/misc.py b/src/ansys/dpf/core/misc.py index c10c42a41b..bc0b7354b7 100644 --- a/src/ansys/dpf/core/misc.py +++ b/src/ansys/dpf/core/misc.py @@ -183,9 +183,9 @@ def find_ansys(): if base_path is None: return base_path - paths = base_path.glob("v*") + paths = list(base_path.glob("v*")) - if not list(paths): + if not paths: return None versions = {}