Documentation process¶
Basic principles¶
Document in that order: why, what, how¶
Documenting ws4py is an important process since the code doesn’t always carry enough information to understand its design and context. Thus, documenting should target the question “why?” first then the “what?” and “how?”. It’s actually trickier than it sound.
Explicit is better than implicit¶
When you have your nose in the code it may sound straightforward enough not to document certain aspects of pyalm. Remember that PEP 20 principle: Explicit is better than implicit.
Be clear, not verbose¶
Finding the right balance between too much and not enough is hard. Writing good documentation is just difficult. However, you should not be too verbose either.
Add enough details to a section to provide context but don’t flood the reader with irrelevant information.
Show me where you come from¶
Every piece of code should be contextualized and almost every time you should explicitely indicate the import statement so that the reader doesn’t wonder where an object comes from.
Documentation Toolkit¶
pyalm uses the Sphinx documentation generator toolkit so refer to its documentation to learn more on its usage.
Building the documentation is as simple as:
cd docs make html
The generated documentation will be available in docs\_build\html
.