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 Update standards based on Nov 2019 PyHC meeting discussion #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)