Overview
- Title
- write a sphinx code doc styleguide
- Duration
- 336
- Difficulty
- Medium
- Type
- Documentation
- Tags
- rst,sphinx,python
- Mentors
- thomaswaldmann,rb_proj,ronny_pfannschmidt,xoraxax
- Count
- -1
Description
Abstract
For moin 2.0 we use sphinx for documentation. In the past (moin 1.x) we used epydoc to document the code.
Our code's docstrings must be refactored from epydoc to rst format.
To prepare that, you have to create a rst/sphinx _template.py that practically shows the features of sphinx / rst markup we usually want to use for documenting the code.
Review some moin source and make sure that for everything we need, there is an example in _template.py.
Also make sure that result looks pretty good and well structured.
The _template.py should be rather generic code (not moin related), so it maybe can be used by the sphinx project as an example file for other projects.
Details
Part A
Write the basic form of the style guide:
docstrings, like for module or class __init__, args, kw args, return type, return value description
- doc-comments for code lines below it
- headlines, lists, bold, italic, code, references to other classes, etc.
- render it with sphinx, check if it looks ok
- check correctness / completeness
Part B
Apply your own styleguide and transform moin modules using it:
see EasyToDo/make docstrings sphinx compatible you have to do 50% of the stuff specified there
- while doing that, incrementally improve your styleguide with stuff you forgot, change stuff not working good, etc.
Deliverables: a patch or changeset for parts A and B
Skill Requirements
You should have experience with creating code documentation with rst and/or sphinx, this should not be your first work with it.
You also should have python knowledge. Although this is not primarily a coding task, you'll have to make up some example code for _template.py, so you have something to document.
Links
- if you want examples for sphinx/rst usage, have a look at sphinx docs, rst primer, werkzeug and flask code