[capi-sig] Documenting a C/Py API

[Campbell Barton]

grrr my attachment was stripped

here it is inline..

Campbell Barton wrote:
 > 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.
 >
 >
 > _______________________________________________
 > Bf-python mailing list
 > Bf-python at blender.org
 > http://lists.blender.org/mailman/listinfo/bf-python
 >