[Bf-python] Epy Docstrings

[Campbell Barton]

Campbell Barton wrote:
> Revision: 11145
>           http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=11145
> Author:   campbellbarton
> Date:     2007-07-02 14:22:30 +0200 (Mon, 02 Jul 2007)
> 
> Log Message:
> -----------
> Testing a way to have python docs in Blenders PyAPI docstrings.
> rather then maintaining 2 sets of docs which is what we have done for a long time.
> 
> Works for Group and Camera now, here are the results
> http://members.optusnet.com.au/cjbarton/bpy_docs/camera.Camera-class.html
> http://members.optusnet.com.au/cjbarton/bpy_docs/group.Group-class.html
> 
> This means the C docstrings need to contain epydoc formatting (humanly readable) but need to be changed in the C files. though editing be done in py files and the final version copied back into the .c file.
> 
> _epy_write_docstrings.py - extracts epydocs and examples into their own py files.
> _epy_docgen.sh - runs _epy_write_docstrings.py in background mode and then epydoc to make the html docs.
> 
> advantage is less work with duplicate docs, we can automate running all examples within the docs to make sure they work.

Hi, just committed an experimental C docstring/epydoc metrhod of 
maintaining our python API docs. its worth discussing the options for docs.

this is not ideal (epydocs in C are a bit of a kludge) but it as some 
good points and IMHO is better then what we have been doing.

pros:
* 1 set of docs, not 2
* built-in python methods are added, like getitem or __hash__
* we can do preprocessing since the epydocs are made from a script...
* better C docstrings (albeit with a bit of odd epydoc tags) - people do 
use the C docstrings sometimes and at the moment they are not well 
checked - some have mistakes or are quite uninformative.
* extracts examples to py files so we can automate running them all.
* its more flexible, we could for instance have all examples in py files 
and include them when the blender puts the docs together, this would 
also not bloat blender too much with really big docstrings,
* converting existing epydocs into C/epy/docstrings is not hard.

cons:
* editing large docstrings with \n\ at the end of everyline is not nice.
* nonstandard, uses a custom script (~200 lines) to extract and write 
docstrings
* workflow to writing docs is longer since you need to edit the c file, 
compile blender and run the script. If there is a missing tab youd not 
want to do all that again.
... Realisticly its not so bad since you can edit the docs that blender 
spits out and then update the C file once your done, but the process is 
still longer for writing epydocs though arguably better then editing 
docs in 2 places.

* one more hoop to jump through when writing docs - you have to learn 
our way of adding epydocs in C.

  - Even though Id rather not make it harder for new people to come in 
and write docs, so far python scripters have not come up and offered to 
write docs, instead its been the C/API authors - who are alredy familiar 
with the C files, it also seems that very few people besides the API 
devs even use epydoc or have it installed so Im not too worried about this.

Have a look at Camera.c to see what the epy/docstrings look like.

http://projects.blender.org/plugins/scmsvn/viewcvs.php/branches/pyapi_devel/source/blender/python/api2_2x/Group.c?view=markup&root=bf-blender&pathrev=11145

If we deciede this is acceptable I can continue and move other finished 
areas of the new API to epy/docstrings.