A previous discussion is being moved here regarding possible updates to OEP-19 to add clarity to when to use docstrings in modules vs README.rst.
A PR was created with a change here OEP-19: Dev Docs: add clarifications by robrap · Pull Request #135 · openedx/open-edx-proposals · GitHub, but there is still a larger conversation below that has not been resolved.
Ned Batchelder 4:25 PM
…
Also, it has this sentence, “The closer the documentation lives with its corresponding code, the more likely it will be kept up-to-date.” and then a few sentences later, “Documentation should not live within the code itself (e.g., in __init__.py
modules).” Anyone understand why?
…
Nimisha Asthagiri 5:17 PM
The closer the documentation lives with its corresponding code, the more likely it will be kept up-to-date
I intended this to be a principle we would follow - essentially, co-locate docs with the code it corresponds to. So that means: ADRs, READMEs, HowTos.
Documentation should not live within the code itself (e.g., in init .py modules).
I used to put long docstrings in the init modules to explain the purpose of the containing directory. However, we then converged on putting that information in RST docs in the directory. Either as READMEs, HowTos, or ADRs. So we’d like to follow that as a consistent convention. (Besides, Python3 no longer requires the existence of those init modules.)
Put another way, when a new reader of the code approaches a new app in our codebase, they would have a consistent experience and look for a consistent location for initial onboarding docs (R, H, ADRs).
…
Ned Batchelder 4 hours ago
The readme’s outside of the docs directory could be included in publishing if a .rst in the docs directory includes them with a directive. But they will be “static” pages, not dynamically associated with the module name as autodoc would do.
Robert Raposa 4 hours ago
Interesting and stinky. We should keep in mind the various use cases.
Use cases for discovering/reading docs:
- Finding/reading published docs.
- Navigating code in Github
- Search (where?)
Use cases for maintaining docs:
- Finding relevant docs outside of code to update.
- Maintaining appropriate cross-references to docs. (Automate?)
I wonder if we could automate something like pulling in the README when the module’s autodoc is generated, or something like this?