@@ -913,4 +913,115 @@ files for inclusion in the documentation.
913913| examples/02-HFSS/HFSS_Spiral.py | examples-design-and-simulation-of-spiral-inductors.py |
914914+-------------------------------------------------+-------------------------------------------------------+
915915
916- If you have questions about SEO, email the `PyAnsy Core team <pyansys_core_email _>`_.
916+ If you have questions about SEO, email the `PyAnsys Core team <pyansys_core_email _>`_.
917+
918+ Facilitating contributions in the form of examples
919+ --------------------------------------------------
920+
921+ A common challenge in libraries is the lack of examples. Examples are
922+ critical for users to understand how to use the library and present new
923+ functionality. They also serve as a mechanism to educate users on best practices.
924+
925+ To encourage contributions of examples, it is important to provide a clear
926+ structure for contributors to follow. The build process should also be straightforward.
927+
928+ Three best practices for examples are:
929+
930+ - **Providing a template **: Ensures that contributors follow a consistent structure and
931+ simplifies the process of getting started. The template should include all necessary
932+ information, such as the name of the example, a description, and the code itself.
933+ - **Verifying the example **: Ensures that the example works as expected and helps catch
934+ errors before submission. The verification process should involve running the example
935+ and checking the output. If the example fails, it should be easy to identify and fix the issue.
936+ - **Making the example usable in multiple contexts **: Ensures that the example can be
937+ usable by a user reading the documentation, an application engineer using the library
938+ through a notebook, or a developer including the example to the documentation.
939+
940+ Providing a template
941+ ~~~~~~~~~~~~~~~~~~~~
942+
943+ Here are examples of how to promote the use of templates for examples:
944+
945+ - `PyAnsys Geometry examples template <PyAnsys_geometry_examples_template _>`_
946+ - `PyPrimeMesh examples template <PyPrimemesh_examples_template _>`_
947+
948+ These templates are also referenced in the contributing guidelines:
949+
950+ - `PyAnsys Geometry example contribution guidelines <PyAnsys_geometry_examples_contribution _>`_
951+
952+ Verifying examples
953+ ~~~~~~~~~~~~~~~~~~
954+
955+ The verification process depends on the library and the tools used for generating the examples.
956+ Within the PyAnsys ecosystem, Sphinx Gallery and NBSphinx are commonly used to generate examples,
957+ with slightly different build processes for each library.
958+
959+ The following approach can be applied across libraries:
960+
961+ - Create a ``Makefile `` target that runs a specific example.
962+
963+ This target is used to execute the example and check the output. Only one example is build in this
964+ case, making it very useful for documentation builds that last very long. If the example fails,
965+ it should be straightforward to identify and resolve the issue. For instance, PyAnsys Geometry
966+ includes a ``make `` target for this purpose:
967+
968+ .. code-block :: console
969+
970+ ./make.bat single-example examples/01_getting_started/01_math.mystnb
971+
972+ code-block :: console
973+
974+ make single-example examples/01_getting_started/01_math.mystnb
975+
976+ PyAnsys Geometry PR #1893 <PyAnsys_geometry_pull_1893 _>`_
977+ This implementation is specific to NB Sphinx, but the concept of creating a target to run a specific
978+ example and verify its output can be adapted to other libraries.
979+
980+ Making the example usable in multiple contexts
981+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
982+
983+ A core objective when designing examples is to ensure they can be used seamlessly across multiple
984+ contexts: whether it is by end users exploring them interactively, by documentation tools rendering
985+ them for the web, or by engineers verifying their correctness and updating them. Achieving this
986+ flexibility requires a careful balance between accessibility, structure, and maintainability.
987+
988+ A recommended approach to support this goal is to author and maintain examples as plain
989+ Python scripts, but using `Jupytext <Jupytext _>`_ to treat those
990+ scripts as notebooks when needed. Formatting your examples using the
991+ `Jupytext light format <Jupytext_light_format _>`_
992+ makes them fully compatible with JupyterLab, where they can be opened, edited, and
993+ executed just like traditional notebooks - all without needing a IPYNB file. Here is an example
994+ of a Jupytext light format script:
995+
996+ .. code-block :: python
997+
998+ # # Dipole antenna
999+ #
1000+ # Keywords: **HFSS**, **antenna**, **3D component**, **far field**.
1001+ #
1002+ # ## Prerequisites
1003+ #
1004+ # ### Perform imports
1005+ #
1006+ # Import the packages required to run this example.
1007+
1008+ # +
1009+ import os
1010+ import tempfile
1011+ import time
1012+
1013+ from ansys.aedt.core import Hfss
1014+
1015+ # -
1016+
1017+ # ### Define constants
1018+ # Constants help ensure consistency and avoid repetition throughout the example.
1019+
1020+ AEDT_VERSION = " 2025.1"
1021+ NUM_CORES = 4
1022+ NG_MODE = False # Open AEDT UI when it is launched.
1023+
1024+
1025+
1026+ - `PyAEDT examples repository <PyAEDT-examples _>`_
1027+ - `PySpeos repository <PySpeos _>`_
0 commit comments