feat: facilitating example contribution

doc/source/how-to/documenting.rst

@@ -913,4 +913,115 @@ files for inclusion in the documentation.
 | examples/02-HFSS/HFSS_Spiral.py                 | examples-design-and-simulation-of-spiral-inductors.py |
 +-------------------------------------------------+-------------------------------------------------------+
 
-If you have questions about SEO, email the `PyAnsy Core team <pyansys_core_email_>`_.
+If you have questions about SEO, email the `PyAnsys Core team <pyansys_core_email_>`_.
+
+Facilitating contributions in the form of examples
+--------------------------------------------------
+
+A common challenge in libraries is the lack of examples. Examples are
+critical for users to understand how to use the library and present new
+functionality. They also serve as a mechanism to educate users on best practices.
+
+To encourage contributions of examples, it is important to provide a clear
+structure for contributors to follow. The build process should also be straightforward.
+
+Three best practices for examples are:
+
+- **Providing a template**: Ensures that contributors follow a consistent structure and
+  simplifies the process of getting started. The template should include all necessary
+  information, such as the name of the example, a description, and the code itself.
+- **Verifying the example**: Ensures that the example works as expected and helps catch
+  errors before submission. The verification process should involve running the example
+  and checking the output. If the example fails, it should be easy to identify and fix the issue.
+- **Making the example usable in multiple contexts**: Ensures that the example can be
+  usable by a user reading the documentation, an application engineer using the library
+  through a notebook, or a developer including the example to the documentation.
+
+Providing a template
+~~~~~~~~~~~~~~~~~~~~
+
+Here are examples of how to promote the use of templates for examples:
+
+- `PyAnsys Geometry examples template <PyAnsys_geometry_examples_template_>`_
+- `PyPrimeMesh examples template <PyPrimemesh_examples_template_>`_
+
+These templates are also referenced in the contributing guidelines:
+
+- `PyAnsys Geometry example contribution guidelines <PyAnsys_geometry_examples_contribution_>`_
+
+Verifying examples
+~~~~~~~~~~~~~~~~~~
+
+The verification process depends on the library and the tools used for generating the examples.
+Within the PyAnsys ecosystem, Sphinx Gallery and NBSphinx are commonly used to generate examples,
+with slightly different build processes for each library.
+
+The following approach can be applied across libraries:
+
+- Create a ``Makefile`` target that runs a specific example.
+
+This target is used to execute the example and check the output. Only one example is build in this
+case, making it very useful for documentation builds that last very long. If the example fails,
+it should be straightforward to identify and resolve the issue. For instance, PyAnsys Geometry
+includes a ``make`` target for this purpose:
+
+.. code-block:: console
+
+    ./make.bat single-example examples/01_getting_started/01_math.mystnb
+
+.. code-block:: console
+
+    make single-example examples/01_getting_started/01_math.mystnb
+
+The pull request introducing this feature is: `PyAnsys Geometry PR #1893 <PyAnsys_geometry_pull_1893_>`_
+This implementation is specific to NB Sphinx, but the concept of creating a target to run a specific
+example and verify its output can be adapted to other libraries.
+
+Making the example usable in multiple contexts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A core objective when designing examples is to ensure they can be used seamlessly across multiple
+contexts: whether it is by end users exploring them interactively, by documentation tools rendering
+them for the web, or by engineers verifying their correctness and updating them. Achieving this
+flexibility requires a careful balance between accessibility, structure, and maintainability.
+
+A recommended approach to support this goal is to author and maintain examples as plain
+Python scripts, but using `Jupytext <Jupytext_>`_ to treat those
+scripts as notebooks when needed. Formatting your examples using the
+`Jupytext light format <Jupytext_light_format_>`_
+makes them fully compatible with JupyterLab, where they can be opened, edited, and
+executed just like traditional notebooks - all without needing a IPYNB file. Here is an example
+of a Jupytext light format script:
+
+.. code-block:: python
+
+  # # Dipole antenna
+  #
+  # Keywords: **HFSS**, **antenna**, **3D component**, **far field**.
+  #
+  # ## Prerequisites
+  #
+  # ### Perform imports
+  #
+  # Import the packages required to run this example.
+
+  # +
+  import os
+  import tempfile
+  import time
+
+  from ansys.aedt.core import Hfss
+
+  # -
+
+  # ### Define constants
+  # Constants help ensure consistency and avoid repetition throughout the example.
+
+  AEDT_VERSION = "2025.1"
+  NUM_CORES = 4
+  NG_MODE = False  # Open AEDT UI when it is launched.
+
+Here are examples of PyAnsys projects using this approach:
+
+- `PyAEDT examples repository <PyAEDT-examples_>`_
+- `PySpeos repository <PySpeos_>`_

doc/source/links.rst

@@ -50,7 +50,12 @@
 .. _grpc_hello_world: https://github.com/ansys/pyansys-helloworld
 .. _Links_for_pymapdl: https://github.com/ansys/pymapdl/blob/main/doc/source/links.rst
 .. _PyAEDT: https://github.com/ansys/pyaedt
+.. _PyAEDT-examples: https://github.com/ansys/pyaedt-examples
 .. _PyAnsys_geometry_Docker_containers: https://geometry.docs.pyansys.com/version/stable/getting_started/docker/index.html
+.. _PyAnsys_geometry_examples_template: https://geometry.docs.pyansys.com/version/stable/examples/99_misc/template.html
+.. _PyAnsys_geometry_examples_contribution: https://geometry.docs.pyansys.com/version/stable/contributing.html#adding-examples
+.. _PyAnsys_geometry_pull_1893 : https://github.com/ansys/pyansys-geometry/pull/1893
+.. _PyPrimemesh_examples_template: https://prime.docs.pyansys.com/version/stable/examples/gallery_examples/misc/example_template.html#sphx-glr-examples-gallery-examples-misc-example-template-py
 .. _PyAnsys: https://docs.pyansys.com/version/stable/
 .. _PyAnsys Bot: https://github.com/apps/pyansys-bot
 .. _pyansys_proto_generator: https://github.com/ansys/pyansys-protos-generator
@@ -64,6 +69,7 @@
 .. _PyMAPDL Legacy Reader: https://github.com/ansys/pymapdl-reader
 .. _PyMechanical: https://github.com/ansys/pymechanical
 .. _PyMeilisearch: https://pymeilisearch.docs.ansys.com/
+.. _PySpeos: https://github.com/ansys/pyspeos
 .. _PyPIM: https://github.com/ansys/pypim
 .. _python_installer_qt_ui_releases: https://github.com/ansys/python-installer-qt-gui/releases
 .. _review_bot: https://github.com/ansys/review-bot
@@ -79,6 +85,7 @@
 .. _Docker: https://www.docker.com/
 .. _Flake8: https://flake8.pycqa.org/en/latest/
 .. _isort: https://pycqa.github.io/isort/
+.. _Jupytext: https://jupytext.readthedocs.io/en/latest/
 .. _numpy: https://numpy.org/
 .. _pandas: https://pandas.pydata.org/
 .. _pre-commit: https://pre-commit.com/
@@ -99,6 +106,7 @@
 .. _Docutils: https://docutils.sourceforge.io/
 .. _doctest: https://docs.python.org/3/library/doctest.html
 .. _Google_docstrings: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
+.. _Jupytext_light_format: https://jupytext.readthedocs.io/en/latest/formats-scripts.html#the-light-format
 .. _Notepadpp_downloads: https://notepad-plus-plus.org/downloads/
 .. _Notepadpp_searching: https://npp-user-manual.org/docs/searching/
 .. _numpydoc: https://numpydoc.readthedocs.io/en/latest/index.html