Use sphinx for Phatchs documentation

Registered by Stani on 2009-06-15

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

Status:
Complete
Approver:
Stani
Priority:
High
Drafter:
Stani
Direction:
Needs approval
Assignee:
Stani
Definition:
Approved
Series goal:
Accepted for 0.2
Implementation:
Implemented
Milestone target:
milestone icon 0.2.1
Started by
Stani on 2009-08-26
Completed by
Stani on 2009-08-27

Related branches

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

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.

Subscribers

No subscribers.