heliophysicsPy · jtniehof · Oct 19, 2025 · Oct 20, 2025 · jtniehof · Oct 19, 2025
diff --git a/pheps/phep-0007.md b/pheps/phep-0007.md
@@ -0,0 +1,134 @@
+```
+PHEP: 7
+Title: Documentation Standards
+Author: Jonathan T. Niehof <jtniehof@gmail.com> <https://orcid.org/0000-0001-6286-5809>
+Discussions-To: https://github.com/heliophysicsPy/standards/pull/48
+Revision: 1
+Status: Draft
+Type: Standards Track
+Content-Type: text/markdown; charset=UTF-8; variant=CommonMark
+Requires: 4
+Created: 20-Oct-2025
+Post-History: 19-Oct-2025, 20-Oct-2025
+Resolution:
+```
+
+# Abstract
+<a name="abstract"></a>
+This PHEP establishes updated standards for documentation of PyHC projects.
+
+# Motivation
+<a name="motivation"></a>
+The consideration of PHEP 4 on package tiering requires a revisit of our standards to clarify how standards relate to various package tiers. PyHC standards GitHub [pull request #16](https://github.com/heliophysicsPy/standards/pull/16) also provides several suggested updates.
+
+# Rationale
+<a name="rationale"></a>
+PyHC standards GitHub [issue #34](https://github.com/heliophysicsPy/standards/issues/34) opened discussion regarding documentation. [Fall meeting 2024](https://doi.org/10.5281/zenodo.15080483) discussion indicated a need for clarification but few additional hard documentation standards.
+
+This PHEP makes minor changes to the documentation requirements and references additional information on documentation best practices.
+
+# Specification
+<a name="specification"></a>
+Considerable best-practice information is included in [How to Teach This](#how-to-teach-this) but is not considered part of this specification proper.
+
+The current [PyHC standard](https://github.com/heliophysicsPy/standards/blob/main/standards.md#standards) on documentation is explicitly applied to all bronze, silver, and gold tier packages, and is updated to read:
+
+"Standard #8 **Documentation** (PHEP 7):
+
+  1. All functions, classes, and modules in the public application programming interface (API) **must** have documentation strings (docstrings).
+  2. Docstrings **must** follow a convention established by the project. [PEP 257](https://www.python.org/dev/peps/pep-0257/) is a minimum requirement but more extensive conventions such as [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) are recommended.
+  3. Docstrings **must** describe the code’s purpose, describe all inputs and outputs, and provide examples.
+  4. Code not in the public API **should** have docstrings sufficient for maintenance by contributors, including contributors external to the project.
+  5. High level documentation **must** also be provided as guides, tutorials, and developer docs.
+  6. Documentation **must** be provided in version control with the code and be built from the repository into an online format that is publicly readable and linkable; this should almost always be HTML. It is recommended that documentation be built as part of continuous integration (CI).
+  7. Projects **must** describe their documentation conventions and how to contribute to documentation."
+
+# Backwards Compatibility
+<a name="backwards-compatibility"></a>
+This PHEP makes minor changes to existing PyHC documentation standards, largely to clarify current practice. This should require only minor effort to the majority of packages. Some packages may need to make documentation updates to be evaluated at the Bronze tier (or higher). The section "[Changes from the previous standard](#changes-from-the-previous-standard)" may be helpful in preparing such updates.
+
+The best practices are intended in part to improve interoperability between documentation of different projects, facilitating e.g. unified PyHC documentation searching.
+
+# Security Implications
+<a name="security-implications"></a>
+This PHEP raises no security implications as it does not interact with any executing code or provide any coding standards.
+
+# How to Teach This
+<a name="how-to-teach-this"></a>
+## Standards
+Most standards remain unchanged. The approval of this PHEP will help make them and the best practices more visible. Upon approval of this PHEP the included best practices will be advertised at the following telecon, and they will also be provided as a reference for package tiering applications. Reviewers of package tiering should provide feedback related to best practices as an education tool, but not enforce them as part of the review.
+
+For many projects, the documentation standards will require no updates. The key education tool will be project tiering evaluation forms and processes.
+
+### Changes from the previous standard
+<a name="changes-from-the-previous-standard"></a>
+This PHEP makes the following changes relative to the original documentation standard from 2018; projects compliant with the previous standard should only need to review this section:
+
+ * The standard was broken into several sub-standards.
+ * Clarify that documentation standards apply primarily to the public API but that non-public code should have docstrings sufficient to enable maintenance, including by external contributors.
+ * Explicitly require [PEP 257](https://www.python.org/dev/peps/pep-0257/) and recommend [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) or similar convention.
+ * Clarify that docs must be built from the repo into a web-appropriate form, and should be built in CI.
+ * Require that a project document their documentation conventions and how to contribute.
+
+## Best practices
+<a name="best-practices"></a>
+[Reference Implementations](#reference-implementations) provides examples of how these best practices are used in PyHC and other projects.
+
+Many projects use [Sphinx](https://www.sphinx-doc.org/), which is the official documentation package used for Python itself. Sphinx makes it easy to [cross-reference](https://www.sphinx-doc.org/en/master/usage/quickstart.html#intersphinx) other projects using Sphinx and to build human-readable documentation from [docstrings](https://www.sphinx-doc.org/en/master/usage/quickstart.html#autodoc).
+
+Different audiences often benefit from different documentation; [diátaxis](https://diataxis.fr/) provides thoughts on how to target your audience. Readers are unlikely to follow a linear path through your documentation, so it is recommended to extensively cross-reference within documentation, including between documentation with different audiences.
+
+### Read the Docs Integration
+[Read the Docs](https://docs.readthedocs.com/) (RtD) offers hosting for documentation. It builds the documentation automatically from the project repository, which is a good test that the documentation can be built by non-developers! It also provides support for cross-project searches.
+
+If your project has particular documentation needs, RtD allows you to [customize the documentation build](https://docs.readthedocs.com/platform/stable/build-customization.html#override-the-build-process).
+
+# Reference Implementations
+<a name="reference-implementations"></a>
+Several PyHC projects provide examples of best practices for documentation.
+
+[sunpy](https://docs.sunpy.org/):
+
+ * Targets specific audiences on its [opening documentation page](https://docs.sunpy.org/).
+ * Provides [documentation standards](https://docs.sunpy.org/en/latest/dev_guide/contents/documentation.html).
+
+[pySPEDEAS](https://pyspedas.readthedocs.io/):
+
+ * Uses [Read the Docs](https://github.com/spedas/pyspedas/blob/master/.readthedocs.yaml).
+
+[dbprocessing](https://spacepy.github.io/dbprocessing/):
+
+ * Separates [usage documentation](https://spacepy.github.io/dbprocessing/), [developer documentation](https://spacepy.github.io/dbprocessing/developer/), and [API documentation](https://spacepy.github.io/dbprocessing/developer/api.html), cross-referencing between each.
+ * Includes explicit [documentation standards](https://spacepy.github.io/dbprocessing/developer/documentation.html).
+ * Automatically generates all API documentation from docstrings. This uses [custom templates](https://github.com/spacepy/dbprocessing/blob/main/docs/_templates/autosummary/module.rst).
+
+# Rejected Ideas
+<a name="rejected-ideas"></a>
+Discussion before and during the Fall 2024 PyHC meeting indicated no consensus for imposing additional standards in this area, even as "shoulds". The existing standards seemed sufficient and the community lacked broad agreement on anything further.
+
+It was alternatively proposed that a very strict documentation standard may be appropriate for Silver or Gold tiers.
+
+# Open Issues
+<a name="open-issues"></a>
+As written, standard #8 was a single standard of a fairly long paragraph. This is the first time we've had an update that didn't work well as a one-to-one replacement of existing standards, so it's unclear how to proceed. For this PHEP it was broken into several substandards (which can be referred to as 8.1, 8.2, etc.) This does make the nested-list formatting of the standards document a little odd. Alternatively, it could remain as a single (even longer) paragraph. Or it could be replaced with several top-level numbered standards. Or, standard 8 could be a much shorter summary, leaving the detailed substandards to this PHEP.
+
+More / more varied examples for reference implementations would be *very welcome*, particularly if there is any information on *how* the implementations can be reproduced. Be bold and point out where your project does well!
+
+More information on RtD would be useful...where in the RtD documentation should PyHC developers look for the most important information?
+
+# Revisions
+Revision 1 (pending): Initial approval.
+
+# Copyright
+<a name="copyright"></a>
+This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. It should be cited as:
+```
+@techreport(phep9999,
+  author = {Jonathan T. Niehof},
+  title  = {Documentation Standards},
+    year = {2025},
+    type = {PHEP},
+  number = {7},
+     doi = {10.5281/zenodo.XXXXXXXX}
+)
+```
diff --git a/standards.md b/standards.md
@@ -29,7 +29,16 @@ Definitions:
 5. **License**: Projects must provide a license. Projects should use permissive licenses for open source scientific software (e.g., the BSD 2-clause, BSD 3-clause, or BSD+Patent licenses). Copyleft licenses such as GPL are not recommended and OSI-approved permissive licenses are recommended.
 6. **Version control**: All code must use version control. It is strongly recommended that projects make use of a distributed version control system (e.g., git).
 7. **Coding Style**: Projects must adopt the basic style recommendations of [PEP 8](https://www.python.org/dev/peps/pep-0008/) and static analysis tools should be used to identify deviations from the basic style recommendations (e.g. pylint, flake8, pycodestyle).
-8. **Documentation**: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard [conventions](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code's purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
+8. **Documentation**:
+
+    1. All functions, classes, and modules in the public application programming interface (API) **must** have documentation strings (docstrings).
+    2. Docstrings **must** follow a convention established by the project. [PEP 257](https://www.python.org/dev/peps/pep-0257/) is a minimum requirement but more extensive conventions such as [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) are recommended.
+    3. Docstrings **must** describe the code’s purpose, describe all inputs and outputs, and provide examples.
+    4. Code not in the public API **should** have docstrings sufficient for maintenance by contributors, including contributors external to the project.
+    5. High level documentation **must** also be provided as guides, tutorials, and developer docs.
+    6. Documentation **must** be provided in version control with the code and be built from the repository into an online format that is publicly readable and linkable; this should almost always be HTML. It is recommended that documentation be built as part of continuous integration (CI).
+    7. Projects **must** describe their documentation conventions and how to contribute to documentation.
+
 9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System[link] and acceptance[link] testing are also recommended.
 10. **Dependencies**: Projects should import the minimum number of packages necessary. 	Adding new dependencies should be a __considered__ decision.
 11. **Python 3**: All packages must be compatible or work towards being compatible with Python 3. Providing ongoing support for Python 2 is not recommended as the end of life for Python 2 is January 1, 2020 (see [PEP 373](https://www.python.org/dev/peps/pep-0373/)).