From 79590b656790becef5af390e1bb212c5aa6a8e43 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 26 Nov 2024 16:46:55 +0100 Subject: [PATCH] feat: added sphinx hook and mordern download buttons --- doc/source/conf.py | 39 +++++++++++++++++++ doc/source/examples/ex_cfx_static_mixer.rst | 20 +++++++--- .../examples/ex_fluent_2d_heat_exchanger.rst | 20 +++++++--- doc/source/examples/ex_fluent_nozzle.rst | 23 +++++++---- doc/source/examples/ex_lsdyna_job.rst | 20 +++++++--- .../examples/ex_mapdl_linked_analyses.rst | 20 +++++++--- .../examples/ex_mapdl_tire_performance.rst | 20 +++++++--- doc/source/examples/ex_motorbike_frame.rst | 20 +++++++--- .../examples/ex_motorbike_frame_query.rst | 24 ++++++++---- doc/source/examples/ex_python_two_bar.rst | 20 +++++++--- doc/source/examples/index.rst | 16 ++++++++ 11 files changed, 192 insertions(+), 50 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 182c2398..48dd89b4 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,9 +1,12 @@ # Sphinx documentation configuration file from datetime import datetime import os +import pathlib +import shutil import sys from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black +import sphinx from ansys.hps.client import __version__ @@ -327,3 +330,39 @@ def prepare_jinja_env(jinja_env) -> None: "ANSYS Help - ", ), } + + +def copy_download_files_to_source_dir(app: sphinx.application.Sphinx) -> None: + """ + Copy zipped example files to target directory at build time + + Parameters + ---------- + app : sphinx.application.Sphinx + 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("*"): + if file_path.is_file(): + shutil.copy(file_path, DOWNLOAD_FILES_DIR) + + +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", copy_download_files_to_source_dir) diff --git a/doc/source/examples/ex_cfx_static_mixer.rst b/doc/source/examples/ex_cfx_static_mixer.rst index 9f3b599b..b951a9d3 100644 --- a/doc/source/examples/ex_cfx_static_mixer.rst +++ b/doc/source/examples/ex_cfx_static_mixer.rst @@ -1,15 +1,14 @@ .. _example_cfx_static_mixer: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the CFX static mixer example. + CFX static mixer ================ This example shows how to submit a CFX static mixer model for solving on Ansys HPS. -.. only:: builder_html - - You can download the :download:`ZIP file <../../../build/cfx_static_mixer.zip>` for - the CFX static mixer example and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` script for this example: .. literalinclude:: ../../../examples/cfx_static_mixer/project_setup.py @@ -23,3 +22,14 @@ This example uses this ``exec_cfx.py`` execution script instead of a solver comm :language: python :lines: 23- :caption: exec_cfx.py + +Download the ZIP file for the CFX static mixer example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/cfx_static_mixer.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/ex_fluent_2d_heat_exchanger.rst b/doc/source/examples/ex_fluent_2d_heat_exchanger.rst index 29f811e0..6aebbdb3 100644 --- a/doc/source/examples/ex_fluent_2d_heat_exchanger.rst +++ b/doc/source/examples/ex_fluent_2d_heat_exchanger.rst @@ -1,18 +1,28 @@ .. _example_fluent_2d_heat_exchanger: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the Fluent 2D heat exchanger example. + Fluent 2D heat exchanger ======================== This example shows how to submit a simple Fluent solve job to Ansys HPS. The model consists of a 2D heat exchanger. -.. only:: builder_html - - You can download the :download:`ZIP file <../../../build/fluent_2d_heat_exchanger.zip>` for the Fluent 2D heat - exchanger example and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` script for this example: .. literalinclude:: ../../../examples/fluent_2d_heat_exchanger/project_setup.py :language: python :lines: 23- :caption: project_setup.py + +Download the ZIP file for the fluent 2D heat exchanger example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/fluent_2d_heat_exchanger.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/ex_fluent_nozzle.rst b/doc/source/examples/ex_fluent_nozzle.rst index 640800fb..a6d10d9b 100644 --- a/doc/source/examples/ex_fluent_nozzle.rst +++ b/doc/source/examples/ex_fluent_nozzle.rst @@ -1,21 +1,30 @@ .. _example_fluent_nozzle: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the Fluent nozzle example. + Fluent nozzle ============= This example shows how to submit a Fluent nozzle model for solving on Ansys HPC Platform Services. -.. only:: builder_html - - You can download the :download:`ZIP file <../../../build/fluent_nozzle.zip>` for the - Fluent nozzle example and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` script for this example: - .. literalinclude:: ../../../examples/fluent_nozzle/project_setup.py :language: python :lines: 23- :caption: project_setup.py -The example uses an execution script stored server side. \ No newline at end of file +The example uses an execution script stored server side. + +Download the ZIP file for the fluent nozzle example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/fluent_nozzle.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/ex_lsdyna_job.rst b/doc/source/examples/ex_lsdyna_job.rst index 46e18e62..a4b978ab 100644 --- a/doc/source/examples/ex_lsdyna_job.rst +++ b/doc/source/examples/ex_lsdyna_job.rst @@ -1,5 +1,9 @@ .. _example_lsdyna_job: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the LS-DYNA job submission example. + LS-DYNA job submission ====================== @@ -28,14 +32,20 @@ The job consists of two tasks: python -m pip install tqdm humanize -.. only:: builder_html - - You can dowlonad the :download:`ZIP file <../../../build/lsdyna_cylinder_plate.zip>` for - the LS-DYNA job submission example and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` script for this example: .. literalinclude:: ../../../examples/lsdyna_cylinder_plate/lsdyna_job.py :language: python :lines: 23- :caption: lsdyna_job.py + +Download the ZIP file for the LS-DYNA job submission example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/lsdyna_cylinder_plate.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/ex_mapdl_linked_analyses.rst b/doc/source/examples/ex_mapdl_linked_analyses.rst index 1e600e74..e844e4b9 100644 --- a/doc/source/examples/ex_mapdl_linked_analyses.rst +++ b/doc/source/examples/ex_mapdl_linked_analyses.rst @@ -1,5 +1,9 @@ .. _example_mapdl_linked_analyses: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the MAPDL linked analyses example. + MAPDL linked analyses ===================== @@ -23,14 +27,20 @@ as a multi-task job to HPS. The script shows two possible ways to submit the ind In both cases, output files from upstream tasks are used as inputs of downstream tasks. -.. only:: builder_html - - You can download the :download:`ZIP file <../../../build/mapdl_linked_analyses.zip>` for the - MAPDL linked analyses example and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` file for this project:. .. literalinclude:: ../../../examples/mapdl_linked_analyses/project_setup.py :language: python :lines: 23- :caption: project_setup.py + +Download the ZIP file for the MAPDL linked analyses example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/mapdl_linked_analyses.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/ex_mapdl_tire_performance.rst b/doc/source/examples/ex_mapdl_tire_performance.rst index 9f18da70..3e481674 100644 --- a/doc/source/examples/ex_mapdl_tire_performance.rst +++ b/doc/source/examples/ex_mapdl_tire_performance.rst @@ -1,5 +1,9 @@ .. _example_mapdl_tire_performance: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the MAPDL tire performance example. + MAPDL tire performance ======================= @@ -8,14 +12,20 @@ performance simulation example included in the technology demonstration guide (t Solution convergence (GST) and contact status (CND) tracking files are periodically collected while the job is running. -.. only:: builder_html - - You can download the :download:`ZIP file <../../../build/mapdl_tyre_performance.zip>` - for the MAPDL tire performance example and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` file for this project: .. literalinclude:: ../../../examples/mapdl_tyre_performance/project_setup.py :language: python :lines: 23- :caption: project_setup.py + +Download the ZIP file for the MAPDL tire performance example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/mapdl_tyre_performance.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/ex_motorbike_frame.rst b/doc/source/examples/ex_motorbike_frame.rst index 32d0c739..84d57015 100644 --- a/doc/source/examples/ex_motorbike_frame.rst +++ b/doc/source/examples/ex_motorbike_frame.rst @@ -1,5 +1,9 @@ .. _example_mapdl_motorbike_frame: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the MAPDL motorbike frame example. + MAPDL motorbike frame: Project creation ======================================= @@ -23,14 +27,20 @@ For more information about this finite element model and its parametrization, se for Design Optimization of a Tubular Steel Trellis Motorbike-Frame", 2003 by U. M. Fasel, O. Koenig, M. Wintermantel and P. Ermanni. -.. only:: builder_html - - You can download the :download:`ZIP file <../../../build/mapdl_motorbike_frame.zip>` for the MAPDL motorbike frame example - and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` script for this example: .. literalinclude:: ../../../examples/mapdl_motorbike_frame/project_setup.py :language: python :lines: 23- :caption: project_setup.py + +Download the ZIP file for the MAPDL motorbike frame example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/mapdl_motorbike_frame.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/ex_motorbike_frame_query.rst b/doc/source/examples/ex_motorbike_frame_query.rst index a3a58572..422881d6 100644 --- a/doc/source/examples/ex_motorbike_frame_query.rst +++ b/doc/source/examples/ex_motorbike_frame_query.rst @@ -1,21 +1,29 @@ .. _example_mapdl_motorbike_frame_query: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the MAPDL motorbike frame example. + MAPDL motorbike frame: Project query ==================================== This example builds upon the :ref:`example_mapdl_motorbike_frame` example. It shows how to query resources of an existing project and how to download output files. -.. only:: builder_html - - .. only:: builder_html - - You can download the :download:`ZIP file <../../../build/mapdl_motorbike_frame.zip>` for the MAPDL - motorbike frame example and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` file for this project: .. literalinclude:: ../../../examples/mapdl_motorbike_frame/project_query.py :language: python :lines: 23- - :caption: project_query.py \ No newline at end of file + :caption: project_query.py + +Download the ZIP file for the MAPDL motorbike frame example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/mapdl_motorbike_frame.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/ex_python_two_bar.rst b/doc/source/examples/ex_python_two_bar.rst index b9fed249..9870dd45 100644 --- a/doc/source/examples/ex_python_two_bar.rst +++ b/doc/source/examples/ex_python_two_bar.rst @@ -1,5 +1,9 @@ .. _example_python_two_bar: +.. note:: + + Go to the `bottom of this page`_ to download the ZIP file for the two-bar truss example. + Two-bar truss ============= @@ -8,14 +12,20 @@ This example shows how to create an HPS project solving a two-bar truss problem For the original problem description, see R.L. Fox, *Optimization Methods in Engineering Design*, Addison Wesley, 1971. Also see `Optimization Methods for Engineering Design `_. -.. only:: builder_html - - You can download the :download:`ZIP file <../../../build/python_two_bar_truss_problem.zip>` for the two-bar truss - example and use a tool such as 7-Zip to extract the files. - Here is the ``project_setup.py`` script for this example: .. literalinclude:: ../../../examples/python_two_bar_truss_problem/project_setup.py :language: python :lines: 23- :caption: project_setup.py + +Download the ZIP file for the two-bar truss example and use +a tool such as 7-Zip to extract the files. + +.. _bottom of this page: + +.. button-link:: ../_downloads/python_two_bar_truss_problem.zip + :color: black + :expand: + + Download ZIP file \ No newline at end of file diff --git a/doc/source/examples/index.rst b/doc/source/examples/index.rst index e52ac93a..3e6f5f54 100644 --- a/doc/source/examples/index.rst +++ b/doc/source/examples/index.rst @@ -1,5 +1,10 @@ .. _examples: +.. note:: + Go to the `bottom of this page`_ to download the ZIP file containing the resources required + to follow all examples. A link to download the required resources for each example + is also available on each example page. + Examples ======== @@ -54,3 +59,14 @@ one :download:`ZIP file <../../../build/pyhps_examples.zip>`. - Submit a CFX solve job to the HPS server using an execution script. * - :ref:`example_python_two_bar` - Create an HPS project that solves a two-bar truss problem with Python. + +A link to download the required resources is available on each example page. If desired, +you can download the required resources for all examples through the link below. + +.. _bottom of this page: + +.. button-link:: ../_downloads/pyhps_examples.zip + :color: black + :expand: + + Download ZIP file for all examples \ No newline at end of file