Use sphinx for Phatchs documentation
Automatically generate for:
- API with doctests (developer)
- action reference (end user)
(We should check that action reference does not conflict with api as eg we don't want doctests in an end user action reference.)
Handwritten tutorials with restructured text (end user).
Blueprint information
Related branches
Related bugs
Sprints
Whiteboard
15-06-09 Juho:
I just gave a go today at using doctests and nose for some quick testing today. It doesn't work out of box due to imports (there's some conflict with translation "_").
It's worth a while to consider the whole process from blueprint to actual working code. In my view only doctests won't cut it. I see development process working as follows:
1. Write blueprint + discuss about basic requirements.
2. Write tests based on 1 or figure out more corner cases to test.
3. Write implementation based on tests (TDD).
4. If it's not ok yet, go back to 2.
5. Ready patch.
So in my view unittests would reflect the mapping of requirements to tests. Note that the main point of these tests is to communicate the interface of the code, not every detail of the actual implementation. Doctests would work on more atomic level testing individual functions, some of which unittests implemented this way cannot directly access to.
I'm sure this workflow is not without its problems. Sometimes it can be tough to come up with proper tests (good blueprints should help in this!).
TODO:
- everyone should add docstrings to his code for sphinx
