From 9c87120bd127e6ac700b618db20a8dcc76b10509 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 09:58:14 +0200 Subject: [PATCH 1/2] Add how-to for writing documentation. --- .../source/how-to/contribute/documentation.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/source/how-to/contribute/documentation.md diff --git a/docs/source/how-to/contribute/documentation.md b/docs/source/how-to/contribute/documentation.md new file mode 100644 index 0000000..d84bae8 --- /dev/null +++ b/docs/source/how-to/contribute/documentation.md @@ -0,0 +1,27 @@ +# Write Documentation + +The documentation for pyAML has been separated into parts to make it more modular and easier to maintain. The documentation consists of: + +- **Ecosystem documentation**: contains documentation for the whole ecosystem. This includes tutorials, how-to guides and explanation. + + This documentation is hosted in its own repository https://github.com/python-accelerator-middle-layer/documentation and published to GitHub pages at https://python-accelerator-middle-layer.github.io/documentation/. Information about how to contribute and build it is available in the repository README. + +- **Package documentation**: each package also its own documentation. This is primarily meant for API documentation but can also include other parts if needed for that specific package. + + This documentation is hosted inside the package repository. It is built and published by readthedocs to allow to publish several version. For it to automatically build, the repository needs to be linked to a project on readthedocs. + + On readthedocs it is possible to configure to build on pull requests. If this has been activated a link appears in the GitHub pull request where you can view the built documentation as part of the review. + + A template for the package documentation is included in the [pyaml-repository-template](https://github.com/python-accelerator-middle-layer/pyaml-repository-template) which can be used to add documentation for a new package. + +## Docstring Format + +pyAML uses NumPy style docstrings. An example of the format is available at [Example NumPy Style Python Docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html) + +For pyAML the following has been decided: + +- Classes should have a class level docstring. This should include description of the class, list of constructor parameters and an example configuration if the class can be included in the configuration. If using the documentation template, docstrings in the `__init__` will be ignored. + +- Attributes, properties and methods should have their own docstrings. + +If you follow these guidelines the documentation will look nice both when building the readthedocs and when the users use `help` in the Python environment. \ No newline at end of file From f34c0c22674691a71e395a1172c075065d28134a Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 11:07:23 +0200 Subject: [PATCH 2/2] Clean up an bug fix of the documentation how-to. --- docs/source/how-to/contribute/documentation.md | 11 +++++++---- docs/source/how-to/index.md | 3 ++- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/source/how-to/contribute/documentation.md b/docs/source/how-to/contribute/documentation.md index d84bae8..c8e3430 100644 --- a/docs/source/how-to/contribute/documentation.md +++ b/docs/source/how-to/contribute/documentation.md @@ -4,11 +4,14 @@ The documentation for pyAML has been separated into parts to make it more modula - **Ecosystem documentation**: contains documentation for the whole ecosystem. This includes tutorials, how-to guides and explanation. - This documentation is hosted in its own repository https://github.com/python-accelerator-middle-layer/documentation and published to GitHub pages at https://python-accelerator-middle-layer.github.io/documentation/. Information about how to contribute and build it is available in the repository README. + This documentation is hosted in its own repository and published to GitHub pages. Information about how to contribute and build it is available in the repository README. -- **Package documentation**: each package also its own documentation. This is primarily meant for API documentation but can also include other parts if needed for that specific package. + Repository: + GitHub page: . - This documentation is hosted inside the package repository. It is built and published by readthedocs to allow to publish several version. For it to automatically build, the repository needs to be linked to a project on readthedocs. +- **Package documentation**: each package also its own documentation. This is primarily meant for API documentation but can also include other parts if needed for that specific package. + + This documentation is hosted inside the package repository. It is built and published by [readthedocs](https://about.readthedocs.com/) to allow to publish several versions. For it to automatically build, the repository needs to be linked to a project on readthedocs. On readthedocs it is possible to configure to build on pull requests. If this has been activated a link appears in the GitHub pull request where you can view the built documentation as part of the review. @@ -16,7 +19,7 @@ The documentation for pyAML has been separated into parts to make it more modula ## Docstring Format -pyAML uses NumPy style docstrings. An example of the format is available at [Example NumPy Style Python Docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html) +PyAML uses NumPy style docstrings. An example of the format is available at [Example NumPy Style Python Docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html). For pyAML the following has been decided: diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md index 7a075ab..11ea6cc 100644 --- a/docs/source/how-to/index.md +++ b/docs/source/how-to/index.md @@ -43,5 +43,6 @@ virtual-accelerator/apptainer :caption: Contribute contribute/contribute -contribute/release.md +contribute/documentation +contribute/release ```