From c89b7caf63873939ec0c33d4c844465f122af4cc Mon Sep 17 00:00:00 2001 From: moe-ad Date: Thu, 28 Nov 2024 11:00:18 +0100 Subject: [PATCH 1/5] feat: combined pre-build scripts into a single sphinx build-time hook --- archive_examples.py | 92 --------------------------------------------- doc/source/conf.py | 89 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 74 insertions(+), 107 deletions(-) delete mode 100644 archive_examples.py diff --git a/archive_examples.py b/archive_examples.py deleted file mode 100644 index 8e48385d..00000000 --- a/archive_examples.py +++ /dev/null @@ -1,92 +0,0 @@ -# Copyright (C) 2022 - 2024 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - -import os -from zipfile import ZipFile - - -def archive_examples(): - """Create a zip archive for each listed example included in the examples folder.""" - - examples = { - "mapdl_motorbike_frame": [ - "project_setup.py", - "project_query.py", - "exec_mapdl.py", - "motorbike_frame_results.txt", - "motorbike_frame.mac", - ], - "mapdl_tyre_performance": [ - "project_setup.py", - "tire_performance_simulation.mac", - "2d_tire_geometry.iges", - ], - "mapdl_linked_analyses": [ - "project_setup.py", - "prestress.dat", - "modal.dat", - "harmonic.dat", - ], - "lsdyna_cylinder_plate": [ - "lsdyna_job.py", - "cylinder_plate.k", - "postprocess.cfile", - ], - "python_two_bar_truss_problem": [ - "project_setup.py", - "exec_python.py", - "evaluate.py", - "input_parameters.json", - ], - "fluent_2d_heat_exchanger": [ - "project_setup.py", - "heat_exchanger.jou", - "heat_exchanger.cas.h5", - ], - "fluent_nozzle": [ - "project_setup.py", - "solve.jou", - "nozzle.cas", - ], - "cfx_static_mixer": [ - "project_setup.py", - "exec_cfx.py", - "runInput.ccl", - "StaticMixer_001.cfx", - "StaticMixer_001.def", - ], - } - - os.makedirs("build", exist_ok=True) - for name, files in examples.items(): - with ZipFile(os.path.join("build", f"{name}.zip"), "w") as zip_archive: - for file in files: - zip_archive.write(os.path.join("examples", name, file), file) - - with ZipFile(os.path.join("build", f"pyhps_examples.zip"), "w") as zip_archive: - for name, files in examples.items(): - for file in files: - zip_archive.write(os.path.join("examples", name, file), os.path.join(name, file)) - - -if __name__ == "__main__": - archive_examples() diff --git a/doc/source/conf.py b/doc/source/conf.py index 48dd89b4..516856a2 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,9 +1,10 @@ # Sphinx documentation configuration file from datetime import datetime import os -import pathlib +from pathlib import Path import shutil import sys +from zipfile import ZipFile from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black import sphinx @@ -331,10 +332,9 @@ def prepare_jinja_env(jinja_env) -> None: ), } - -def copy_download_files_to_source_dir(app: sphinx.application.Sphinx) -> None: +def archive_examples(app: sphinx.application.Sphinx) -> None: """ - Copy zipped example files to target directory at build time + Create a zip archive for each listed example included in the examples folder. Parameters ---------- @@ -342,17 +342,76 @@ def copy_download_files_to_source_dir(app: sphinx.application.Sphinx) -> None: Sphinx application instance containing the all the doc build configuration. """ - - # archive_examples.py in the root directory is being run before doc build (via tox) - # we simply need to copy the into the _download target defined in the .rst source files. - SOURCE_DIR = pathlib.Path(app.srcdir) - ZIPPED_FILES_DIR = SOURCE_DIR.parent.parent / "build" - DOWNLOAD_FILES_DIR = SOURCE_DIR.parent / "_build" / "html" / "_downloads" - DOWNLOAD_FILES_DIR.mkdir(exist_ok=True) - - for file_path in ZIPPED_FILES_DIR.glob("*"): + EXAMPLES = { + "mapdl_motorbike_frame": [ + "project_setup.py", + "project_query.py", + "exec_mapdl.py", + "motorbike_frame_results.txt", + "motorbike_frame.mac", + ], + "mapdl_tyre_performance": [ + "project_setup.py", + "tire_performance_simulation.mac", + "2d_tire_geometry.iges", + ], + "mapdl_linked_analyses": [ + "project_setup.py", + "prestress.dat", + "modal.dat", + "harmonic.dat", + ], + "lsdyna_cylinder_plate": [ + "lsdyna_job.py", + "cylinder_plate.k", + "postprocess.cfile", + ], + "python_two_bar_truss_problem": [ + "project_setup.py", + "exec_python.py", + "evaluate.py", + "input_parameters.json", + ], + "fluent_2d_heat_exchanger": [ + "project_setup.py", + "heat_exchanger.jou", + "heat_exchanger.cas.h5", + ], + "fluent_nozzle": [ + "project_setup.py", + "solve.jou", + "nozzle.cas", + ], + "cfx_static_mixer": [ + "project_setup.py", + "exec_cfx.py", + "runInput.ccl", + "StaticMixer_001.cfx", + "StaticMixer_001.def", + ], + } + SOURCE_DIR = Path(app.srcdir) + ROOT_PATH = SOURCE_DIR.parent.parent + + # Create zip files for each example + build_path = ROOT_PATH / "build" + build_path.mkdir(exist_ok=True) + for name, files in EXAMPLES.items(): + with ZipFile(build_path / f"{name}.zip", "w") as zip_archive: + for file in files: + zip_archive.write(ROOT_PATH / "examples" / name / file, file) + + with ZipFile(build_path / "pyhps_examples.zip", "w") as zip_archive: + for name, files in EXAMPLES.items(): + for file in files: + zip_archive.write(ROOT_PATH / "examples" / name / file, Path(name) / file) + + # Copy zipped example files to target directory at build time + download_files_dir = SOURCE_DIR.parent / "_build" / "html" / "_downloads" + download_files_dir.mkdir(exist_ok=True) + for file_path in build_path.glob("*"): if file_path.is_file(): - shutil.copy(file_path, DOWNLOAD_FILES_DIR) + shutil.copy(file_path, download_files_dir) def setup(app: sphinx.application.Sphinx) -> None: @@ -365,4 +424,4 @@ def setup(app: sphinx.application.Sphinx) -> None: Sphinx application instance containing the all the doc build configuration. """ - app.connect("builder-inited", copy_download_files_to_source_dir) + app.connect("builder-inited", archive_examples) From 7f917d97aa4f651f01dc8e0a302c2cb9dfbf9ec2 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Thu, 28 Nov 2024 11:21:13 +0100 Subject: [PATCH 2/5] feat: updated tox.ini to call sphinx-build directly --- tox.ini | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tox.ini b/tox.ini index 434899be..5398953d 100644 --- a/tox.ini +++ b/tox.ini @@ -44,6 +44,7 @@ deps = -e .[doc] allowlist_externals = make commands = - python archive_examples.py - make -C doc html - make -C doc pdf \ No newline at end of file + sphinx-build -M html "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto + sphinx-build -M latex "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto + cd "{toxinidir}/doc/_build/latex" && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true + (test -f "{toxinidir}/doc/_build/latex/*.pdf" && echo pdf exists) || exit 1 \ No newline at end of file From 12da443e99c9e4d87d9503630d18164e2c0e92a5 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 28 Nov 2024 10:31:55 +0000 Subject: [PATCH 3/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index 516856a2..2b4b91b9 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -332,6 +332,7 @@ def prepare_jinja_env(jinja_env) -> None: ), } + def archive_examples(app: sphinx.application.Sphinx) -> None: """ Create a zip archive for each listed example included in the examples folder. From d7e7d6a5961cbc0b0b94e8af887f9c27ef20f42a Mon Sep 17 00:00:00 2001 From: moe-ad Date: Thu, 28 Nov 2024 12:41:50 +0100 Subject: [PATCH 4/5] feat: implemented review comments and updated affected actions --- .github/workflows/ci_cd.yml | 7 ------- .github/workflows/nightly.yml | 7 ------- tox.ini | 5 +---- 3 files changed, 1 insertion(+), 18 deletions(-) diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml index 116fbe69..ed84e515 100644 --- a/.github/workflows/ci_cd.yml +++ b/.github/workflows/ci_cd.yml @@ -101,13 +101,6 @@ jobs: path: doc/_build/html retention-days: 7 - - name: Upload PDF Documentation - uses: actions/upload-artifact@v4 - with: - name: documentation-pdf - path: doc/_build/latex/*.pdf - retention-days: 7 - smoke-tests: name: Build and Smoke tests runs-on: ${{ matrix.os }} diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 7c8c550e..f1d6e295 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -130,10 +130,3 @@ jobs: name: documentation-html path: doc/_build/html retention-days: 7 - - - name: Upload PDF Documentation - uses: actions/upload-artifact@v4 - with: - name: documentation-pdf - path: doc/_build/latex/*.pdf - retention-days: 7 \ No newline at end of file diff --git a/tox.ini b/tox.ini index 5398953d..3b6fe085 100644 --- a/tox.ini +++ b/tox.ini @@ -44,7 +44,4 @@ deps = -e .[doc] allowlist_externals = make commands = - sphinx-build -M html "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto - sphinx-build -M latex "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto - cd "{toxinidir}/doc/_build/latex" && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true - (test -f "{toxinidir}/doc/_build/latex/*.pdf" && echo pdf exists) || exit 1 \ No newline at end of file + sphinx-build -M html "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto \ No newline at end of file From fef5eb56215400962ba6ed7cd95c5984f2a503aa Mon Sep 17 00:00:00 2001 From: moe-ad Date: Sun, 1 Dec 2024 15:33:01 +0100 Subject: [PATCH 5/5] feat: implemented review comments --- doc/source/conf.py | 111 +++++++++++++++++++++++---------------------- 1 file changed, 57 insertions(+), 54 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 2b4b91b9..e7f0befe 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -11,6 +11,56 @@ from ansys.hps.client import __version__ +# Constants declaration +EXAMPLES = { + "mapdl_motorbike_frame": [ + "project_setup.py", + "project_query.py", + "exec_mapdl.py", + "motorbike_frame_results.txt", + "motorbike_frame.mac", + ], + "mapdl_tyre_performance": [ + "project_setup.py", + "tire_performance_simulation.mac", + "2d_tire_geometry.iges", + ], + "mapdl_linked_analyses": [ + "project_setup.py", + "prestress.dat", + "modal.dat", + "harmonic.dat", + ], + "lsdyna_cylinder_plate": [ + "lsdyna_job.py", + "cylinder_plate.k", + "postprocess.cfile", + ], + "python_two_bar_truss_problem": [ + "project_setup.py", + "exec_python.py", + "evaluate.py", + "input_parameters.json", + ], + "fluent_2d_heat_exchanger": [ + "project_setup.py", + "heat_exchanger.jou", + "heat_exchanger.cas.h5", + ], + "fluent_nozzle": [ + "project_setup.py", + "solve.jou", + "nozzle.cas", + ], + "cfx_static_mixer": [ + "project_setup.py", + "exec_cfx.py", + "runInput.ccl", + "StaticMixer_001.cfx", + "StaticMixer_001.def", + ], +} + sys.path.append(os.path.abspath(os.path.dirname(__file__))) # -- Project information ----------------------------------------------------- @@ -343,72 +393,25 @@ def archive_examples(app: sphinx.application.Sphinx) -> None: Sphinx application instance containing the all the doc build configuration. """ - EXAMPLES = { - "mapdl_motorbike_frame": [ - "project_setup.py", - "project_query.py", - "exec_mapdl.py", - "motorbike_frame_results.txt", - "motorbike_frame.mac", - ], - "mapdl_tyre_performance": [ - "project_setup.py", - "tire_performance_simulation.mac", - "2d_tire_geometry.iges", - ], - "mapdl_linked_analyses": [ - "project_setup.py", - "prestress.dat", - "modal.dat", - "harmonic.dat", - ], - "lsdyna_cylinder_plate": [ - "lsdyna_job.py", - "cylinder_plate.k", - "postprocess.cfile", - ], - "python_two_bar_truss_problem": [ - "project_setup.py", - "exec_python.py", - "evaluate.py", - "input_parameters.json", - ], - "fluent_2d_heat_exchanger": [ - "project_setup.py", - "heat_exchanger.jou", - "heat_exchanger.cas.h5", - ], - "fluent_nozzle": [ - "project_setup.py", - "solve.jou", - "nozzle.cas", - ], - "cfx_static_mixer": [ - "project_setup.py", - "exec_cfx.py", - "runInput.ccl", - "StaticMixer_001.cfx", - "StaticMixer_001.def", - ], - } - SOURCE_DIR = Path(app.srcdir) - ROOT_PATH = SOURCE_DIR.parent.parent + + source_dir = Path(app.srcdir) + root_path = source_dir.parent.parent # Create zip files for each example - build_path = ROOT_PATH / "build" + build_path = root_path / "build" build_path.mkdir(exist_ok=True) for name, files in EXAMPLES.items(): with ZipFile(build_path / f"{name}.zip", "w") as zip_archive: for file in files: - zip_archive.write(ROOT_PATH / "examples" / name / file, file) + zip_archive.write(root_path / "examples" / name / file, file) with ZipFile(build_path / "pyhps_examples.zip", "w") as zip_archive: for name, files in EXAMPLES.items(): for file in files: - zip_archive.write(ROOT_PATH / "examples" / name / file, Path(name) / file) + zip_archive.write(root_path / "examples" / name / file, Path(name) / file) # Copy zipped example files to target directory at build time - download_files_dir = SOURCE_DIR.parent / "_build" / "html" / "_downloads" + download_files_dir = source_dir.parent / "_build" / "html" / "_downloads" download_files_dir.mkdir(exist_ok=True) for file_path in build_path.glob("*"): if file_path.is_file():