feat: facilitating example contribution

doc/source/how-to/documenting.rst

@@ -913,4 +913,62 @@ 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.
+
+Two 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.
+
+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. 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.

doc/source/links.rst

@@ -51,6 +51,10 @@
 .. _Links_for_pymapdl: https://github.com/ansys/pymapdl/blob/main/doc/source/links.rst
 .. _PyAEDT: https://github.com/ansys/pyaedt
 .. _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