From 33985fcae7118db540cf78a76b1598f3958c8dbd Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 18 Jan 2022 12:42:31 -0500 Subject: [PATCH 1/6] Fix minor doc issues --- doc/source/guidelines/dev_practices.rst | 66 +++++++++++++------------ doc/source/overview/basic.rst | 60 +++++++++++----------- doc/source/overview/contributing.rst | 39 ++++++++------- 3 files changed, 84 insertions(+), 81 deletions(-) diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index 99e6a0f71..4d8b434c5 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -3,14 +3,14 @@ Development Practices ===================== This page explains how PyAnsys development is conducted. When -contributing directly to PyAnsys libraries, use these general +contributing to a PyAnsys repository, use these general coding paradigms: #. Follow the `Zen of Python `__. As silly as core Python developers are sometimes, there's much to be gained by following the basic guidelines listed in PEP 20. As suggested in these guidelines, focus on making your additions intuitive, novel, - and helpful for PyAnsys library users. When in doubt, use ``import this``. + and helpful for PyAnsys users. When in doubt, use ``import this``. For Ansys code quality standards, see :ref:`coding_style`. #. Document your contributions. Include a docstring for any added @@ -31,13 +31,14 @@ coding paradigms: Contributing Through GitHub --------------------------- -To submit new code to a PyAnsys Library: +To submit new code to a PyAnsys repository: #. `Fork `_ - the respective library's GitHub repository and then clone - the forked repository to your computer. + the respective GitHub repository and then clone the forked repository + to your computer. -#. In your local repository, create a branch. See `Branching Model <#Branching Model>`__. +#. In your local repository, create a branch. See :ref:`branch_naming`and + and `Branching Model <#Branching Model>`__. #. Add your new feature and commit it locally. Be sure to commit frequently as the ability to revert to past commits is often helpful, @@ -54,15 +55,15 @@ Once you have tested your branch locally, create a PR and target your merge to ``main``. This will automatically run CI testing and verify that your changes will work across all supported platforms. -For code verification, someone from the development team for the PyAnsys library -will review your code to verify that it meets our standards. Once your code -is approved, if you have write permission, you may merge the PR branch. If you -don't have write permission, the reviewer or someone else with write permission -will merge and delete the PR branch. +For code verification, someone from the PyAnsys development team will review your +code to verify that it meets our standards. Once your code is approved, if you +have write permission, you may merge the PR branch. If you don't have write +permission, the reviewer or someone else with write permission will merge your +PR and then delete your PR branch. If your PR branch is a ``fix/`` branch, do not delete it because it may be necessary to -merge your PR branch with the current release branch. See the next section for branch -naming conventions. +merge your PR branch with the current release branch. The next section explains our +branch naming conventions. .. _branch_naming: @@ -124,7 +125,8 @@ like this: Documentation ------------- -Documentation for a PyAnsys library is generated from three sources: +The source and content for documentation varies from project to project. For a PyAnsys library, +documentation is generated from three sources: - Docstrings from the library's classes, functions, and modules using `sphinx.ext.autodoc `_. @@ -170,12 +172,12 @@ stable release of the PyAEDT documentation is version of this documentation is ``_. The latest development version is kept up-to-date automatically via GitHub actions. -Building the Documentation Locally -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can build and verify a library's HTML documentation locally by installing -Sphinx and other documentation build dependencies. +Building Documentation Locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can build and verify the HTML documentation for a PyAnsys project locally +by installing Sphinx and other documentation build dependencies. -#. Optionally install the library in development mode: +#. Optionally install the project in development mode: .. code:: @@ -201,14 +203,14 @@ Otherwise, if running on Windows, build the documentation: cd doc make.bat html -#. After documentation builds successfully locally, use your - browser to open the file ``index.html`` in ``doc/_build/html/`` - to review it. +#. After documentation builds successfully locally, navigate to + ``doc/_build/html/`` and use your browser to open the + ``index.html`` so that you can review the documenation. Continuous Integration and Continuous Delivery (CI/CD) ------------------------------------------------------ -A PyAnsys library uses continuous integration (CI) and continuous delivery (CD) +A PyAnsys project uses continuous integration (CI) and continuous delivery (CD) to automate building, testing, and deployment tasks. The CI pipeline is deployed on both GitHub Actions and Azure Pipelines and performs the following tasks: @@ -220,7 +222,7 @@ tasks: Branching Model --------------- -The branching model for a PyAnsys library enables rapid development of +The branching model for a PyAnsys project enables rapid development of features without sacrificing stability. The model closely follows the `Trunk Based Development `_ approach: @@ -276,11 +278,10 @@ Release procedures follow for major and minor releases. #. After building the documentation, open the local build and examine the examples for any obvious issues. -#. Update the version numbers in - ``ansys///_version.py`` and commit this file. Push the - branch to GitHub and create a new PR for this release that merges - it to ``main``. While effort is focused on the release, development - to ``main`` should be limited. +#. Update the version numbers in ``ansys///_version.py`` + and commit this file. Push the branch to GitHub and create a new PR + for this release that merges it to ``main``. While effort is focused + on the release, development to ``main`` should be limited. #. Wait for the PyAnsys developers and community to functionally test the new release. Testors should locally install this branch and use it in @@ -327,11 +328,12 @@ should not wait until a minor release. These are the steps for a patch release: an opportunity to validate and approve the bug fix release. Any additional hotfixes should be outside of this PR. -#. When the PR is approved, merge it with the release branch, but not with - ``main`` as there is no reason to increment the version of the ``main`` branch. +#. When the PR is approved, merge it with the release branch but not with + ``main`` because there is no reason to increment the version of the + ``main`` branch. #. Create a tag from the release branch with the applicable version number as described in the previous section. -4. If deemed necessary, create and add release notes as described in the +#. If deemed necessary, create and add release notes as described in the previous section. diff --git a/doc/source/overview/basic.rst b/doc/source/overview/basic.rst index d08b63548..bca113fe2 100644 --- a/doc/source/overview/basic.rst +++ b/doc/source/overview/basic.rst @@ -1,41 +1,41 @@ Quick Start Guide ================= -This is a brief overview on how to get started right away with your own PyAnsys library on the `PyAnsys GitHub Organization`_ - -#. **Create the Repository:** Create a new repository from the - `pyansys/template`_. See - `Creating a repository from a template`_. Be sure to start as a - private repository. - -#. **Rename the Package:** Rename ``ansys/product/library`` to match - your product or library. For example ``ansys/mapdl/core``. Do the - same in ``setup.py``. Do this as a pull request. In fact, only add - code as pull requests (don't push to main). - -#. **Add Source:** Add your source files to - ``ansys//``, or create them. At the same time, +This is a brief overview on how to get started right away with your own PyAnsys +repository on the `PyAnsys GitHub Organization`_. A repository is generally a +project for a particular PyAnsys library or tool. + +#. **Create the repository:** Create a repository from the + `pyansys/template`_. See `Creating a repository from a template`_. + Be sure that the `repository visibility`_ is initially private. + +#. **Rename the package:** Rename ``ansys/product/library`` to match + your product or library. For example, the package name for + PyMAPDL is ``ansys/mapdl/core``. Do the + same renaming in ``setup.py``. Do this as a pull request. In fact, only add + code as pull requests. Do not push to ``main``.) + +#. **Add source:** Add your source files to + ``ansys//`` or create them. At the same time, add unit tests to ``tests/`` following the `pytest`_ convention. Be sure to maintain sufficient coverage when adding your library. See `pytest-cov`_. .. note:: - If your tests require an active service, - application, or product, be sure to setup this application to run - in an automated manner. - -#. **Documentation:** Update documentation at ``doc/``. There are two - types of docs, User-Guide and API. Be sure that both are updated. - See :ref:`api_documentation`. - -#. **Package Release:** When ready to release your package publicly, - contact alexander.kaszynski@ansys.com to obtain the release - checklist in regards to official Ansys approval. Once the - checklist is complete, change the `repository visibility`_, - create a release branch. - -The manner of the source and content of the documentation will vary -from project to project. + If your tests require an active service, application, or product, + be sure to set up this application to run in an automated manner. + +#. **Update documentation:** The documentation source and content will + vary from project to project. In ``doc/``, there are folders for + different types of documentation, which can include guides, examples, + and API. Ensure that all documentation is updated. See :ref:`api_documentation`. + +#. **Prepare the package for release:** When you are ready to release + your package publicly, email `pyansys.support@ansys.com `_ + to obtain the release checklist for obtaining official Ansys approval. + Once you have completed this checklist, change the `repository visibility`_ + to public and create a release branch. + .. todo:: diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index e1bf2e56b..786d6ef89 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -11,12 +11,12 @@ encourage you to submit questions, report bugs, request new features, contribute code, and start discussions. This page provides general information about contributing to a -PyAnsys library. Contribution information specific to a particular -library appears on the ``Contributing`` page in the respective -library's documentation, including: +PyAnsys repository. Contribution information specific to a particular +repository appears on the ``Contributing`` page in the respective +repository's documentation, including: - Instructions for cloning the source repository from GitHub -- URL to the library's ``Issues`` page +- URL to the repository's ``Issues`` page Creating Issues --------------- @@ -36,8 +36,9 @@ it with a comment that explains why you have done so. If you need to contact the PyAnsys project support team directly, email `pyansys.support@ansys.com `_. For convenience, here are URLs for ``Issues`` pages for -Ansys product repositories: +public Ansys repositories: +- `OpenAPI Client Issues `_ - `PyAEDT Issues `_ - `PyDPF-Core Issues `_ - `PyDPF-Post Issues `_ @@ -46,16 +47,16 @@ Ansys product repositories: Submitting Questions ~~~~~~~~~~~~~~~~~~~~ -For general or technical questions about a PyAnsys library, its +For general or technical questions about a PyAnsys repository, its applications, or software usage, create issues on the respective -library's ``Issues`` page. This allows PyAnsys developers and +repository's ``Issues`` page. This allows PyAnsys developers and community members with the needed expertise to collectively address them. It also makes their responses available to all users. Reporting Bugs ~~~~~~~~~~~~~~ -If you encounter a bug or your workflow crashes while using a -PyAnsys library, create an issue on the respective library's +If you encounter a bug or your workflow crashes while using code +in a PyAnsys repository, create an issue on the respective repository's ``Issues`` page and tag it with an appropriate label so that it can be promptly addressed. In describing the issue, be as descriptive as possible so that the issue can be reproduced. Whenever possible, @@ -64,8 +65,8 @@ the community to address the issue. Requesting New Features ~~~~~~~~~~~~~~~~~~~~~~~ -We encourage you to submit ideas for improving PyAnsys libraries. -To suggest a new feature, create an issue on the respective library's +We encourage you to submit ideas for improving PyAnsys repositories. +To suggest a new feature, create an issue on the respective repository's ``Issues`` page and tag it with the ``Feature Request`` label. Use a descriptive title and provide ample background information to help the community decide how the feature might be implemented. For example, @@ -87,20 +88,20 @@ When you are ready to start contributing code, see: Starting Discussions -------------------- For general questions about development practices, you should create discussions -rather than issues. The repository for each PyAnsys library has its own -``Discussions`` page. For example, to ask a question about a PyMAPDL development -practice, you would create a discussion on this library's `Discussions `_ +rather than issues. Each PyAnsys repository has its own ``Discussions`` page. +For example, to ask a question about a PyMAPDL development practice, you would +create a discussion on the `PyMAPDL Discussions `_ page. It is possible for discussions to lead to the creation of issues. .. note:: - Because the ``Discussions`` page is still a beta feature on GitHub, usage + Because the ``Discussions`` page is still a GitHub beta feature, usage may change in the future. Cloning the Source Repository ----------------------------- As mentioned earlier, specific instructions for cloning a source repository from GitHub appear on the ``Contributing`` page in the -respective library's documentation. In the following code for cloning and +respective repository's documentation. In the following code for cloning and installing the latest version of a PyAnsys repository, ```` is a placeholder for the name of the repository. @@ -119,7 +120,7 @@ you would run the following: cd pymapdl pip install -e . -If you want to eventually push a contribution to the official +If you want to eventually push a contribution to a PyAnsys repository, consider creating a `fork `_ of the repository. For information on how to contribute through GitHub, see :ref:`development_practices`, paying particular attention to :ref:`branch_naming` @@ -128,8 +129,8 @@ when you are ready to create a pull request. Licensing --------- All contributed code will be licensed under the MIT License. For more information, see -:ref:`license_file`. The ``LICENSE`` file with the MIT License must be included in -the root directory of the repository for a PyAnsys library. +:ref:`license_file`. The ``LICENSE`` file containing the MIT License must be included in +the root directory of a PyAnsys repository. If you did not write the code that you are contributing yourself, it is your responsibility to ensure that the existing license for this code is compatible and From d56053497e933ab4f7fa0fa1d9808355e80c8ad5 Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 18 Jan 2022 12:48:19 -0500 Subject: [PATCH 2/6] Fix use of both interpreted text role prefix and reference suffix --- doc/source/guidelines/dev_practices.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index 4d8b434c5..3a606ad61 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -38,7 +38,7 @@ To submit new code to a PyAnsys repository: to your computer. #. In your local repository, create a branch. See :ref:`branch_naming`and - and `Branching Model <#Branching Model>`__. + and :ref:`branching_model`. #. Add your new feature and commit it locally. Be sure to commit frequently as the ability to revert to past commits is often helpful, @@ -220,6 +220,8 @@ tasks: - Spelling and style verification - Documentation build +.. _branching_model: + Branching Model --------------- The branching model for a PyAnsys project enables rapid development of From 06b961037a8607af456807874aca7a0b17dbd806 Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 18 Jan 2022 12:51:42 -0500 Subject: [PATCH 3/6] Fix branch_naming`and and :ref:`branching_model --- doc/source/guidelines/dev_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index 3a606ad61..cd065d814 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -38,7 +38,7 @@ To submit new code to a PyAnsys repository: to your computer. #. In your local repository, create a branch. See :ref:`branch_naming`and - and :ref:`branching_model`. + :ref:`branching_model`. #. Add your new feature and commit it locally. Be sure to commit frequently as the ability to revert to past commits is often helpful, From 0941b92a984119304e40dc9ce9941ba1d2348d01 Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 18 Jan 2022 12:56:55 -0500 Subject: [PATCH 4/6] Tried yet another approach to get past line 40 --- doc/source/guidelines/dev_practices.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index cd065d814..44fe161c7 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -37,8 +37,9 @@ To submit new code to a PyAnsys repository: the respective GitHub repository and then clone the forked repository to your computer. -#. In your local repository, create a branch. See :ref:`branch_naming`and - :ref:`branching_model`. +#. In your local repository, create a branch. See :ref:`branch_naming`. + Comprehensive information on our model for branching is availible in + `Branching Model <#Branching Model>`__. #. Add your new feature and commit it locally. Be sure to commit frequently as the ability to revert to past commits is often helpful, From 92445cf0d46e824350346198db638c9d40d8c112 Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Wed, 19 Jan 2022 13:29:45 -0500 Subject: [PATCH 5/6] Additional doc edits --- doc/source/guidelines/dev_practices.rst | 16 ++++---- doc/source/overview/basic.rst | 11 +++-- doc/source/overview/contributing.rst | 54 ++++++++++++------------- 3 files changed, 39 insertions(+), 42 deletions(-) diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index 44fe161c7..de3f71bab 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -126,7 +126,7 @@ like this: Documentation ------------- -The source and content for documentation varies from project to project. For a PyAnsys library, +The source and content for documentation varies from repository to repository. For a PyAnsys library, documentation is generated from three sources: - Docstrings from the library's classes, functions, and modules using @@ -164,14 +164,14 @@ and will be compiled dynamically during the build process. Always ensure that examples run properly locally because they will be verified through the CI performed via GitHub Actions. -Documentation for the latest stable release of a PyAnsys libary is accessible -from its repository. You can access the latest development version of the +Documentation for the latest stable release of a PyAnsys library is accessible +from its repository. You can generally access the latest development version of the documentation tracking the ``main`` branch by adding the prefix ``dev.`` to -the URL for the latest stable release. For example, the URL for the latest -stable release of the PyAEDT documentation is -``_, and the URL for the latest development -version of this documentation is ``_. The -latest development version is kept up-to-date automatically via GitHub actions. +the URL for the latest stable release. For example, the URL for documentation of the +latest stable release of PyAEDT is ``_, and +the URL for the latest documentation for the development version of PyAEDT is +``_. The latest development versions of both +the library and its documentation are kept up-to-date automatically via GitHub actions. Building Documentation Locally ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/overview/basic.rst b/doc/source/overview/basic.rst index bca113fe2..1f96a2c24 100644 --- a/doc/source/overview/basic.rst +++ b/doc/source/overview/basic.rst @@ -3,7 +3,7 @@ Quick Start Guide This is a brief overview on how to get started right away with your own PyAnsys repository on the `PyAnsys GitHub Organization`_. A repository is generally a -project for a particular PyAnsys library or tool. +project for a particular PyAnsys library. #. **Create the repository:** Create a repository from the `pyansys/template`_. See `Creating a repository from a template`_. @@ -16,17 +16,16 @@ project for a particular PyAnsys library or tool. code as pull requests. Do not push to ``main``.) #. **Add source:** Add your source files to - ``ansys//`` or create them. At the same time, - add unit tests to ``tests/`` following the `pytest`_ convention. - Be sure to maintain sufficient coverage when adding your library. - See `pytest-cov`_. + ``ansys//`` or create them. Also add unit tests to + ``tests/`` following the `pytest`_ convention. Be sure to maintain + sufficient coverage when adding your library. See `pytest-cov`_. .. note:: If your tests require an active service, application, or product, be sure to set up this application to run in an automated manner. #. **Update documentation:** The documentation source and content will - vary from project to project. In ``doc/``, there are folders for + vary from repository to _repository. In ``doc/``, there are folders for different types of documentation, which can include guides, examples, and API. Ensure that all documentation is updated. See :ref:`api_documentation`. diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index 786d6ef89..f74d95ccf 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -10,10 +10,10 @@ our libraries powerful tools for all users. As such, we encourage you to submit questions, report bugs, request new features, contribute code, and start discussions. -This page provides general information about contributing to a -PyAnsys repository. Contribution information specific to a particular +This page provides general information about contributing code to a +PyAnsys respository. Contribution information specific to a particular repository appears on the ``Contributing`` page in the respective -repository's documentation, including: +respository's documentation, including: - Instructions for cloning the source repository from GitHub - URL to the repository's ``Issues`` page @@ -38,7 +38,7 @@ PyAnsys project support team directly, email `pyansys.support@ansys.com `_ +- `OpenAPI Common Issues `_ - `PyAEDT Issues `_ - `PyDPF-Core Issues `_ - `PyDPF-Post Issues `_ @@ -47,41 +47,39 @@ public Ansys repositories: Submitting Questions ~~~~~~~~~~~~~~~~~~~~ -For general or technical questions about a PyAnsys repository, its -applications, or software usage, create issues on the respective -repository's ``Issues`` page. This allows PyAnsys developers and -community members with the needed expertise to collectively address -them. It also makes their responses available to all users. +For general or technical questions about the code in a PyAnsys repository or +about its application or software usage, create issues on the ``Issues`` page +of the repository. This allows PyAnsys developers and community members with +the needed expertise to collectively address them. It also makes their responses +available to all users. Reporting Bugs ~~~~~~~~~~~~~~ -If you encounter a bug or your workflow crashes while using code -in a PyAnsys repository, create an issue on the respective repository's -``Issues`` page and tag it with an appropriate label so that it -can be promptly addressed. In describing the issue, be as descriptive -as possible so that the issue can be reproduced. Whenever possible, -provide a traceback, screenshots, and sample files that might help -the community to address the issue. +If you encounter a bug or your workflow crashes while using code in a PyAnsys +repository, create an issue on the repository's ``Issues`` page and tag it with +an appropriate label so that it can be promptly addressed. In describing the +issue, be as descriptive as possible so that the issue can be reproduced. +Whenever possible, provide a traceback, screenshots, and sample files that might +help the community to address the issue. Requesting New Features ~~~~~~~~~~~~~~~~~~~~~~~ -We encourage you to submit ideas for improving PyAnsys repositories. -To suggest a new feature, create an issue on the respective repository's -``Issues`` page and tag it with the ``Feature Request`` label. Use a -descriptive title and provide ample background information to help the -community decide how the feature might be implemented. For example, -if you would like to see a reader added for a specific file format, -in the issue, provide a link to documentation for this file -format and possibly some sample files and screenshots. The community -will then use the issue thread to discuss the request and -provide feedback on how the feature might best be implemented. +We encourage you to submit ideas for improving the code in a PyAnsys +repository. To suggest a new feature, create an issue on the repository's +``Issues`` page and tag this issue with the ``Feature Request`` label. +Use a descriptive title and provide ample background information to help the +community decide how the feature might be implemented. For example, if you +would like to see a reader added for a specific file format, in the issue, +provide a link to documentation for this file format and possibly some sample +files and screenshots. The community will then use the issue thread to discuss +the request and provide feedback on how the feature might best be implemented. Contributing New Code --------------------- When you are ready to start contributing code, see: -- :ref:`development_practices` for information on how development is - conducted in PyAnsys repositories +- :ref:`development_practices` for information on how PyAnsys development is + conducted - :ref:`best_practices` for information on how to style and format your code to adhere to PyAnsys standards From 5e3454fee45059406d68f24cfc31ea111f11fda6 Mon Sep 17 00:00:00 2001 From: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Date: Wed, 19 Jan 2022 16:48:18 -0500 Subject: [PATCH 6/6] Update doc/source/guidelines/dev_practices.rst Co-authored-by: Alex Kaszynski --- doc/source/guidelines/dev_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/guidelines/dev_practices.rst b/doc/source/guidelines/dev_practices.rst index de3f71bab..7d562486f 100644 --- a/doc/source/guidelines/dev_practices.rst +++ b/doc/source/guidelines/dev_practices.rst @@ -168,7 +168,7 @@ Documentation for the latest stable release of a PyAnsys library is accessible from its repository. You can generally access the latest development version of the documentation tracking the ``main`` branch by adding the prefix ``dev.`` to the URL for the latest stable release. For example, the URL for documentation of the -latest stable release of PyAEDT is ``_, and +latest stable release of PyAEDT is ``_, and the URL for the latest documentation for the development version of PyAEDT is ``_. The latest development versions of both the library and its documentation are kept up-to-date automatically via GitHub actions.