Revise "documentation" standard

[jtniehof]

(Broader context at the end).

This issue is to discuss a potential PHEP to replace the "documentation" portion of the existing PyHC standards: to lay out what looks like the current standards, and allow for suggested changes.

The existing standard is:

8. Documentation: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard conventions (e.g. numpydoc). 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.

16 has suggested updates.

Does it make sense to have this as a single PHEP or should it be lumped in with some of the other categories?

Broader context: I envision a process of "patriating the constitution" where we revisit the existing standards documents and incorporate them into PHEPs, potentially updated, that are explicitly noted as replacing the relevant standards. We probably do not want one PHEP per standard. Our previous grouping in the review guidelines seems a good start.

[jtniehof]

This is tough one: maybe the standards portion is small, but I can see a lot of scope for best practices, how to get the most out of Sphinx, integrating with RtD, etc. So maybe this would involve a standards-track PHEP with a large "how to teach this" section and a robust reference implementation, perhaps even a reference implementation that's maintained by the community.

As far as the core requirement, changes could be:

• incorporate #16's change of public functions, classes, etc.
• explicitly make PEP257 a "must", not buried in a link :)
• document a project's documentation conventions and how to contribute

I can think of a lot of candidate "shoulds":

• Sphinx / intersphinx
• numpydoc
• autodoc/autosummary
• Build / check the docs in CI
• Reference Diátaxis
• Robust use of cross-references (within the documentation and to other documentation)

[sapols]

The Fall Meeting revealed very little appetite for the recommended "shoulds" here. More emphasis on making sure docstrings are used consistently and documentation is available online on a website (i.e. not a PDF dropped in the git repo).

Someone pointed out that ReadTheDocs doesn't require sphinx; it apparently works with all kinds of documentation (e.g. see this link?). It'd be great to have language in the PHEP like "if you want to be included in a cool global documentation search thing, add your docs to ReadTheDocs by doing ".

[jtniehof]

Consensus from my scrawled notes (complementing Shawn's notes):

• The current standard is pretty good for "musts"
• Some sort of wordsmithing is necessary to indicate documentation of public API
• Support for a "should" build docs in CI, possibly "should" for using ReadTheDocs (or Shawn's wording of the benefits of RtD).
• Make explicit the requirement that the documentation be built from a repository and placed on the web (discussion was "not PDF" so probably explicit about built into HTML)
• "How to teach this" section of a documentation PHEP can have references for documentation best practices. "Reference implementation" can point to existing PyHC projects with examples of what they did well. Notes on RtD customization
• At this level it may make sense for the PHEP to apply to all tiers, although @Cadair did make the suggestion of having a pretty tight documentation standard and have it be silver (please correct if I misremember)