From def994c4019ac542c417062abda91a1d38ea3ef8 Mon Sep 17 00:00:00 2001 From: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Date: Fri, 9 May 2025 15:12:29 +0200 Subject: [PATCH 01/10] feat: facilitating example contribution --- doc/source/how-to/documenting.rst | 59 ++++++++++++++++++++++++++++++- doc/source/links.rst | 4 +++ 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 3221cbb01..4e8264a32 100644 --- a/doc/source/how-to/documenting.rst +++ b/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 `_. +If you have questions about SEO, email the `PyAnsys Core team `_. + +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 `_ +- `PyPrimeMesh examples template `_ + +These templates are also referred to in the contributing guidelines: + +- `PyAnsys Geometry example contribution guidelines `_ + +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 `_ +This implementation is specific for NB Sphinx, but the idea is to create a target that runs a specific example and checks the output. diff --git a/doc/source/links.rst b/doc/source/links.rst index 578ace064..cf7f18e48 100644 --- a/doc/source/links.rst +++ b/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 From 92908d05d164d6d70940084b8220bac2f6817ece Mon Sep 17 00:00:00 2001 From: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Date: Fri, 9 May 2025 15:36:08 +0200 Subject: [PATCH 02/10] feat: enhancements --- doc/source/how-to/documenting.rst | 47 ++++++++++++++++--------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 4e8264a32..1f84abdb8 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -918,22 +918,21 @@ If you have questions about SEO, email the `PyAnsys Core team `_ - `PyPrimeMesh examples template `_ -These templates are also referred to in the contributing guidelines: +These templates are also referenced in the contributing guidelines: - `PyAnsys Geometry example contribution guidelines `_ 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. +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. -However, the following approach could be useful for all libraries: +The following approach can be applied across libraries: -- Create a Makefile target that only runs a specific example. +- Create a ``Makefile`` target that 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: +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 @@ -969,5 +969,6 @@ An example of this is the ``make`` target in PyAnsys Geometry: make single-example examples/01_getting_started/01_math.mystnb -The pull request in which this was added is: `PyAnsys Geometry PR #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. +The pull request introducing this feature is: `PyAnsys Geometry PR #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. From ea6293b006cdf3da9b217628694582f077532be8 Mon Sep 17 00:00:00 2001 From: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Date: Fri, 9 May 2025 21:00:24 +0200 Subject: [PATCH 03/10] Update doc/source/how-to/documenting.rst Co-authored-by: Kerry McAdams <58492561+klmcadams@users.noreply.github.com> --- doc/source/how-to/documenting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 1f84abdb8..bc6d99c50 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -937,7 +937,7 @@ Two best practices for examples are: Providing a template ~~~~~~~~~~~~~~~~~~~~ -Here is an example of how to promote the use of templates for examples: +Here are examples of how to promote the use of templates for examples: - `PyAnsys Geometry examples template `_ - `PyPrimeMesh examples template `_ From fee274a40141da6ef8c645fb701eeb1d8b038b90 Mon Sep 17 00:00:00 2001 From: Sebastien Morais Date: Wed, 14 May 2025 12:17:06 +0200 Subject: [PATCH 04/10] docs: extend with jupytext approach --- doc/source/how-to/documenting.rst | 52 +++++++++++++++++++++++++++++++ doc/source/links.rst | 2 ++ 2 files changed, 54 insertions(+) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index bc6d99c50..40ce3e2d8 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -933,6 +933,9 @@ Two best practices for examples are: - **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 ~~~~~~~~~~~~~~~~~~~~ @@ -972,3 +975,52 @@ includes a ``make`` target for this purpose: The pull request introducing this feature is: `PyAnsys Geometry PR #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's 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. + +To support this goal, we recommend a workflow where examples are authored and maintained as plain +Python scripts, but using `Jupytext `_ to treat those +scripts as notebooks when needed. Formatting your examples using the +`light format `_ +makes them 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 `_ +- `PySpeos repository `_ diff --git a/doc/source/links.rst b/doc/source/links.rst index cf7f18e48..667623c2e 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -50,6 +50,7 @@ .. _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 @@ -68,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 From e23e9df84730db68e854470588b5dea2acd75b50 Mon Sep 17 00:00:00 2001 From: Sebastien Morais Date: Wed, 14 May 2025 14:20:51 +0200 Subject: [PATCH 05/10] fix(docs): wrong link for pyspeos --- doc/source/links.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/links.rst b/doc/source/links.rst index 667623c2e..dc91b73ba 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -69,7 +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 +.. _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 From 996c22f328e1e24bf1fdaa4bd157489ae294d519 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Morais?= <146729917+SMoraisAnsys@users.noreply.github.com> Date: Thu, 15 May 2025 09:07:22 +0200 Subject: [PATCH 06/10] Apply suggestions from code review Co-authored-by: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> --- doc/source/how-to/documenting.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 40ce3e2d8..66c7e2db9 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -935,7 +935,7 @@ Two best practices for examples are: 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. + through a notebook, or a developer including the example to the documentation. Providing a template ~~~~~~~~~~~~~~~~~~~~ @@ -980,11 +980,11 @@ 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's by end users exploring them interactively, by documentation tools rendering +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. -To support this goal, we recommend a workflow where examples are authored and maintained as plain +A recommended approach to support this goal is to author and maintain examples as plain Python scripts, but using `Jupytext `_ to treat those scripts as notebooks when needed. Formatting your examples using the `light format `_ From 5ce05825e01db5688907271cd8175782b7ac205a Mon Sep 17 00:00:00 2001 From: Sebastien Morais Date: Thu, 15 May 2025 09:15:30 +0200 Subject: [PATCH 07/10] refactor: use links file --- doc/source/how-to/documenting.rst | 4 ++-- doc/source/links.rst | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 66c7e2db9..3010dc936 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -985,9 +985,9 @@ them for the web, or by engineers verifying their correctness and updating them. 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 `_ to treat those +Python scripts, but using `Jupytext `_ to treat those scripts as notebooks when needed. Formatting your examples using the -`light format `_ +`Jupytext light format `_ makes them 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: diff --git a/doc/source/links.rst b/doc/source/links.rst index a4911ed25..3b0c7c5f6 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -85,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/ @@ -105,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 From ddb26875336f36dec2d84498b05743ef546f5276 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Morais?= <146729917+SMoraisAnsys@users.noreply.github.com> Date: Thu, 15 May 2025 21:23:15 +0200 Subject: [PATCH 08/10] Update doc/source/how-to/documenting.rst Co-authored-by: Camille Latapie <78221213+clatapie@users.noreply.github.com> --- doc/source/how-to/documenting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 3010dc936..9f7ce850d 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -925,7 +925,7 @@ 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: +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 From 05efe5c0e22cb98802f546a9a7c7710225f4a7e6 Mon Sep 17 00:00:00 2001 From: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> Date: Fri, 16 May 2025 03:28:15 +0200 Subject: [PATCH 09/10] Update doc/source/how-to/documenting.rst --- doc/source/how-to/documenting.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 9f7ce850d..53fa3ce9e 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -960,7 +960,8 @@ 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, +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: From cff58e15d33c83fb29ce6deea9f5398e9a521917 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Morais?= <146729917+SMoraisAnsys@users.noreply.github.com> Date: Sat, 17 May 2025 07:37:26 +0200 Subject: [PATCH 10/10] Update doc/source/how-to/documenting.rst --- doc/source/how-to/documenting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/how-to/documenting.rst b/doc/source/how-to/documenting.rst index 53fa3ce9e..bdd8b0785 100644 --- a/doc/source/how-to/documenting.rst +++ b/doc/source/how-to/documenting.rst @@ -989,7 +989,7 @@ A recommended approach to support this goal is to author and maintain examples a Python scripts, but using `Jupytext `_ to treat those scripts as notebooks when needed. Formatting your examples using the `Jupytext light format `_ -makes them makes them fully compatible with JupyterLab, where they can be opened, edited, and +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: