feat: added sphinx hook and mordern download buttons (#500)

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)

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

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

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.
+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

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

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

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

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

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
+    :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

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 <https://apmonitor.com/me575/uploads/Main/optimization_book.pdf>`_.
 
-.. 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