Documenting¶
As new capabilities are added to the system, they need to be documented.
As the system evolves, outdated documentation needs to be updated, and obsolete documentation needs to be purged.
As the documentation evolves, it needs to be tested to ensure that it is accurate, useable, adequate, and organized.
The workflow used in this system treats working on documentation as a programming and testing task, rather than an exercise in writing. Developers typically like to program. Journeymen developers have used test-driven-devlopment to increase their effectiveness. The goal here is to generate adequate to high quality documentation without getting bogged down with writers block, by relying on a developer’s skillset.
New Capabilities¶
Whenever you work on a new capability, you are likely to install new python packages or other software. You won’t know ahead of time what will be needed in the long term, and if so, the exact configuration. In addition, these configuration steps will not be often repeated, so it is easy to forget the exact steps. To avoid reinventing the wheel, the work in these configuration steps should be captured so that you have the raw material to document or automate the configuration.
At this time, the recommended practice is to create an .rst file for the issue. Run all installation activities from a terminal if possible. Copy the terminal output to the file, and indent it. Lead off with a .. code-block console Sphinx directive.
Auto-Doc Code¶
API documentionation is generated using the sphinx.ext.autodoc extension. As new modules are written, the initial package.rst file needs to generated.
Do not use the -f or –force option. The existing files may contain customizations that you don’t want to lose. Instead, if you want to update an existing file, look at the file. If it doesn’t contain any customization, delete the file, and rebuild the documentation. If it does contain customization, rename the file, regenerate the documentation, and add the customizations back into the autogenerated file. Update git as appropriate.
“A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines. With consistency a great soul has simply nothing to do. He may as well concern himself with his shadow on the wall. Speak what you think now in hard words, and to-morrow speak what to-morrow thinks in hard words again, though it contradict every thing you said to-day. — ‘Ah, so you shall be sure to be misunderstood.’ — Is it so bad, then, to be misunderstood? Pythagoras was misunderstood, and Socrates, and Jesus, and Luther, and Copernicus, and Galileo, and Newton, and every pure and wise spirit that ever took flesh. To be great is to be misunderstood.”
—Ralph Waldo Emerson, 1841
In general, work on high level API documentation, rather than focusing on low level docstrings. With well written Python code, the interpretion of arguments should be pretty straightforward. Strictly applying “complete” docstrings with all arguments documented with small functions is likely to double the size of the code and the effort to maintain it with perhaps 10 percent additional information useful to someone at some time. If some aspect of the code is not straightforward, consider renaming functions and arguments rather than elaborating on the docstrings.
This system relies on Sphinx for documentation. Consequently, docstrings can use Restructured Text markup. Use it to please the consumer of the API documentation, and have them think you are a hot-shot rather than clueless.