feat: facilitating example contribution

Author: RobPasMue

doc/source/how-to/documenting.rst

@@ -913,4 +913,61 @@ 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
+--------------------------------------------------
+
+One of the main challenges we face inside our libraries is the lack of examples. Examples are
+critical for users to understand how to use the library and present new functionality. They are also
+a great mechanism to educate users on the best practices of using it.
+
+When users want to contribute examples, we need to make it as easy as possible for them to do so. This
+means that we need to provide a clear structure for them to follow. We also need to make sure that the
+build process is as simple as possible.
+
+2 best practices for examples are:
+
+- **Providing a template**: This is a great way to ensure that users follow the same structure. It also makes it easy for
+  them to get started. The template should include all the necessary information, such as the name of the
+  example, a description, and the code itself.
+- **Verifying the example**: This is a great way to ensure that the example works as expected. It also helps to catch any
+  errors before they are submitted. The verification process should include running the example and checking
+  the output. If the example fails, it should be easy for the user to fix it.
+
+Providing a template
+~~~~~~~~~~~~~~~~~~~~
+
+Here is an example 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 referred to in the contributing guidelines:
+
+- `PyAnsys Geometry example contribution guidelines <PyAnsys_geometry_examples_contribution_>`_
+
+Verifying examples
+~~~~~~~~~~~~~~~~~~
+
+The verification process will depend on each library and the tools used for generating the examples. Within
+our ecosystem, we are using Sphinx Gallery and NBSphinx to generate the examples, and the build process
+is slightly different for each library.
+
+However, the following approach could be useful for all libraries:
+
+- Create a Makefile target that only runs a specific example.
+
+This target should be used to run the example and check the output. If the example fails, it should be easy for the user to fix it.
+An example of this is the ``make`` target in PyAnsys Geometry:
+
+.. 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 in which this was added is: `PyAnsys Geometry PR #1893 <PyAnsys_geometry_pull_1893_>`_
+This implementation is specific for NB Sphinx, but the idea is to create a target that runs a specific example and checks the output.

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