docs: add example assets button

doc/changelog.d/518.documentation.md

@@ -0,0 +1 @@
+add example assets button

doc/source/_static/assets/download/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!README.md

doc/source/_static/assets/download/README.md

@@ -0,0 +1 @@
+Downloadable assets are stored here.

doc/source/conf.py

@@ -16,6 +16,8 @@
 LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
 os.environ["DOCUMENTATION_BUILDING"] = "true"
 
+logger = logging.getLogger(__name__)
+
 # Project information
 project = "ansys-speos-core"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
@@ -50,7 +52,6 @@
         "pages": ["index"],
     }
 
-
 # Sphinx extensions
 extensions = [
     "numpydoc",
@@ -138,8 +139,9 @@
     nbsphinx_prompt_width = ""
     nbsphinx_prolog = """
 
-    .. grid:: 3
-        :gutter: 1
+    .. grid:: 5
+
+        .. grid-item::
 
         .. grid-item::
             :child-align: center
@@ -159,12 +161,24 @@
 
                 Download as Jupyter notebook :fas:`book`
 
+        .. grid-item::
+            :child-align: center
+
+            .. button-link:: {cname_pref}/{assets_loc}
+               :color: primary
+               :shadow:
+
+                Download example's assets :fa:`file`
+
+        .. grid-item::
+
 ----
 
     """.format(
         cname_pref=f"https://{cname}/version/{get_version_match(version)}",
         python_file_loc="{{ env.docname }}.py",
         ipynb_file_loc="{{ env.docname }}.ipynb",
+        assets_loc="_static/assets/download/",
     )
 
 
@@ -261,6 +275,28 @@ def copy_examples_files_to_source_dir(app: sphinx.application.Sphinx):
         destination_file.write_text(file.read_text(encoding="utf-8"), encoding="utf-8")
 
 
+def copy_assets_to_output_dir(app: sphinx.application.Sphinx, exception: Exception):
+    """Copy the assets directory to the output directory of the documentation.
+
+    Parameters
+    ----------
+    app : sphinx.application.Sphinx
+        Sphinx application instance containing the all the doc build configuration.
+    exception : Exception
+        Exception encountered during the building of the documentation.
+    """
+    if app.builder.name == "html":
+        SOURCE_ASSETS = pathlib.Path(app.outdir) / "_static" / "assets" / "download"
+        ASSETS_DIRECTORY = pathlib.Path(app.outdir).parent.parent.parent / "tests" / "assets"
+
+        logger.info("Extracting assets to output directory...")
+        zip_path = pathlib.Path(shutil.make_archive("assets", "zip", ASSETS_DIRECTORY))
+        zip_path = shutil.move(zip_path, SOURCE_ASSETS / zip_path.name)
+        logger.info(f"Extracted assets to {zip_path}.")
+    else:
+        logger.info(f"Skip assets extraction with build {app.builder.name}.")
+
+
 def remove_examples_from_source_dir(app: sphinx.application.Sphinx, exception: Exception):
     """
     Remove the example files from the documentation source directory.
@@ -274,7 +310,6 @@ def remove_examples_from_source_dir(app: sphinx.application.Sphinx, exception: E
 
     """
     EXAMPLES_DIRECTORY = pathlib.Path(app.srcdir) / "examples"
-    logger = logging.getLogger(__name__)
     logger.info(f"\nRemoving {EXAMPLES_DIRECTORY} directory...")
     shutil.rmtree(EXAMPLES_DIRECTORY)
 
@@ -297,4 +332,5 @@ def setup(app: sphinx.application.Sphinx):
     if BUILD_EXAMPLES:
         app.connect("builder-inited", copy_examples_files_to_source_dir)
         app.connect("build-finished", remove_examples_from_source_dir)
+        app.connect("build-finished", copy_assets_to_output_dir)
         app.connect("build-finished", copy_examples_to_output_dir)

examples/core/lpf-preview.py

@@ -9,9 +9,11 @@
 from ansys.speos.core.simulation import SimulationInteractive
 
 # If using docker container
-tests_data_path = Path("/app") / "assets"
+assets_data_path = Path("/app") / "assets"
 # If using local server
-# tests_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# If using a different path
+# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
 # ## Create connection with speos rpc server
@@ -34,7 +36,7 @@
 # +
 p = Project(
     speos=speos,
-    path=str(tests_data_path / "error_data.speos" / "error_data.speos"),
+    path=str(assets_data_path / "error_data.speos" / "error_data.speos"),
 )
 p.preview(viz_args={"opacity": 0.7})
 # -

examples/core/opt-prop.py

@@ -15,9 +15,11 @@
 from ansys.speos.core import GeoRef, Project, Speos
 
 # If using docker container
-tests_data_path = Path("/app") / "assets"
+assets_data_path = Path("/app") / "assets"
 # If using local server
-# tests_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# If using a different path
+# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
 # ## Create connection with speos rpc server
@@ -73,7 +75,7 @@
 op2 = p.create_optical_property(name="Material.2")
 op2.set_surface_opticalpolished()  # SOP : optical polished
 op2.set_volume_library(
-    path=str(tests_data_path / "AIR.material")
+    path=str(assets_data_path / "AIR.material")
 )  # VOP : selected library via a file .material
 # This optical property will be applied to two bodies named : "TheBodyD" and "TheBodyE".
 op2.set_geometries(

examples/core/part.py

@@ -14,9 +14,11 @@
 from ansys.speos.core import Body, Face, Part, Project, Speos
 
 # If using docker container
-tests_data_path = Path("/app") / "assets"
+assets_data_path = Path("/app") / "assets"
 # If using local server
-# tests_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# If using a different path
+# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
 # ## Create connection with speos rpc server

examples/core/prism-example.py

@@ -11,9 +11,11 @@
 from ansys.speos.core.simulation import SimulationDirect
 
 # If using docker container
-tests_data_path = Path("/app") / "assets"
+assets_data_path = Path("/app") / "assets"
 # If using local server
-# tests_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# If using a different path
+# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
 # ## Create connection with speos rpc server
@@ -28,7 +30,7 @@
 # Load a project from .speos file.
 
 # +
-p = Project(speos=speos, path=str(tests_data_path / "Prism.speos" / "Prism.speos"))
+p = Project(speos=speos, path=str(assets_data_path / "Prism.speos" / "Prism.speos"))
 print(p)
 # -
 

examples/core/project.py

@@ -20,9 +20,11 @@
 from ansys.speos.core.source import SourceSurface
 
 # If using docker container
-tests_data_path = Path("/app") / "assets"
+assets_data_path = Path("/app") / "assets"
 # If using local server
-# tests_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# If using a different path
+# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
 # ## Create connection with speos rpc server
@@ -148,7 +150,7 @@
 # +
 p2 = Project(
     speos=speos,
-    path=str(tests_data_path / "LG_50M_Colorimetric_short.sv5" / "LG_50M_Colorimetric_short.sv5"),
+    path=str(assets_data_path / "LG_50M_Colorimetric_short.sv5" / "LG_50M_Colorimetric_short.sv5"),
 )
 print(p2)
 # -

examples/core/sensor.py

@@ -15,9 +15,11 @@
 )
 
 # If using docker container
-tests_data_path = Path("/app") / "assets"
+assets_data_path = Path("/app") / "assets"
 # If using local server
-# tests_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# If using a different path
+# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
 # ## Create connection with speos rpc server
@@ -43,12 +45,14 @@
 
 # +
 distortion_file_path = str(
-    tests_data_path / "CameraInputFiles" / "CameraDistortion_130deg.OPTDistortion"
+    assets_data_path / "CameraInputFiles" / "CameraDistortion_130deg.OPTDistortion"
 )
-transmittance_file_path = str(tests_data_path / "CameraInputFiles" / "CameraTransmittance.spectrum")
-blue_spectrum_path = str(tests_data_path / "CameraInputFiles" / "CameraSensitivityBlue.spectrum")
-green_spectrum_path = str(tests_data_path / "CameraInputFiles" / "CameraSensitivityGreen.spectrum")
-red_spectrum_path = str(tests_data_path / "CameraInputFiles" / "CameraSensitivityRed.spectrum")
+transmittance_file_path = str(
+    assets_data_path / "CameraInputFiles" / "CameraTransmittance.spectrum"
+)
+blue_spectrum_path = str(assets_data_path / "CameraInputFiles" / "CameraSensitivityBlue.spectrum")
+green_spectrum_path = str(assets_data_path / "CameraInputFiles" / "CameraSensitivityGreen.spectrum")
+red_spectrum_path = str(assets_data_path / "CameraInputFiles" / "CameraSensitivityRed.spectrum")
 
 sensor1 = p.create_sensor(name="Camera.1", feature_type=SensorCamera)
 sensor1.set_distortion_file_uri(uri=distortion_file_path)
@@ -82,12 +86,14 @@
 
 # +
 distortion_file_path = str(
-    tests_data_path / "CameraInputFiles" / "CameraDistortion_130deg.OPTDistortion"
+    assets_data_path / "CameraInputFiles" / "CameraDistortion_130deg.OPTDistortion"
+)
+transmittance_file_path = str(
+    assets_data_path / "CameraInputFiles" / "CameraTransmittance.spectrum"
 )
-transmittance_file_path = str(tests_data_path / "CameraInputFiles" / "CameraTransmittance.spectrum")
-blue_spectrum_path = str(tests_data_path / "CameraInputFiles" / "CameraSensitivityBlue.spectrum")
-green_spectrum_path = str(tests_data_path / "CameraInputFiles" / "CameraSensitivityGreen.spectrum")
-red_spectrum_path = str(tests_data_path / "CameraInputFiles" / "CameraSensitivityRed.spectrum")
+blue_spectrum_path = str(assets_data_path / "CameraInputFiles" / "CameraSensitivityBlue.spectrum")
+green_spectrum_path = str(assets_data_path / "CameraInputFiles" / "CameraSensitivityGreen.spectrum")
+red_spectrum_path = str(assets_data_path / "CameraInputFiles" / "CameraSensitivityRed.spectrum")
 
 sensor2 = p.create_sensor(name="Camera.2", feature_type=SensorCamera)
 sensor2.set_distortion_file_uri(uri=distortion_file_path)

examples/core/simulation.py

@@ -13,9 +13,11 @@
 from ansys.speos.core.simulation import SimulationInteractive, SimulationInverse
 
 # If using docker container
-tests_data_path = Path("/app") / "assets"
+assets_data_path = Path("/app") / "assets"
 # If using local server
-# tests_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# If using a different path
+# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
 # ## Create connection with speos rpc server
@@ -101,7 +103,7 @@
 simulation2_direct = p.create_simulation(name="Simulation.2")
 
 simulation2_direct.set_ambient_material_file_uri(
-    uri=str(tests_data_path / "AIR.material")
+    uri=str(assets_data_path / "AIR.material")
 ).set_colorimetric_standard_CIE_1964().set_weight_none().set_geom_distance_tolerance(
     0.01
 ).set_max_impact(200).set_dispersion(False)
@@ -130,7 +132,7 @@
 # If you don't, you will still only watch what is committed on the server.
 
 # +
-simulation1.set_ambient_material_file_uri(uri=str(tests_data_path / "AIR.material"))
+simulation1.set_ambient_material_file_uri(uri=str(assets_data_path / "AIR.material"))
 simulation1.commit()
 print(simulation1)
 # -

examples/core/source.py

@@ -15,9 +15,11 @@
 )
 
 # If using docker container
-tests_data_path = Path("/app") / "assets"
+assets_data_path = Path("/app") / "assets"
 # If using local server
-# tests_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
+# If using a different path
+# assets_data_path = Path("path/to/downloaded/example/assets")
 # -
 
 # ## Create connection with speos rpc server
@@ -42,7 +44,7 @@
 # The mention "local: " is added when printing the source.
 
 # +
-intensity_file_path = str(tests_data_path / "IES_C_DETECTOR.ies")
+intensity_file_path = str(assets_data_path / "IES_C_DETECTOR.ies")
 
 source1 = p.create_source(name="Luminaire.1", feature_type=SourceLuminaire)  # type luminaire
 source1.set_intensity_file_uri(uri=intensity_file_path)
@@ -64,7 +66,7 @@
 # Setting several more characteristics.
 
 # +
-intensity_file_path = str(tests_data_path / "IES_C_DETECTOR.ies")
+intensity_file_path = str(assets_data_path / "IES_C_DETECTOR.ies")
 
 source2 = p.create_source(name="Luminaire.2", feature_type=SourceLuminaire)
 source2.set_intensity_file_uri(uri=intensity_file_path)
@@ -140,7 +142,7 @@
 # ### ray-file source
 
 # +
-ray_file_path = str(tests_data_path / "Rays.ray")
+ray_file_path = str(assets_data_path / "Rays.ray")
 
 source3 = p.create_source(name="Ray-file.1", feature_type=SourceRayFile)  # type ray file
 source3.set_ray_file_uri(uri=ray_file_path)