[capi-sig] Documenting a C/Py API
cbarton at metavr.com
Mon Jul 2 16:12:46 CEST 2007
grrr my attachment was stripped
here it is inline..
Campbell Barton wrote:
> Campbell Barton wrote:
>> 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
>> 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
> 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.
> * 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.
> * editing large docstrings with \n\ at the end of everyline is not nice.
> * nonstandard, uses a custom script (~200 lines) to extract and write
> * 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
> Have a look at Camera.c to see what the epy/docstrings look like.
> 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
More information about the capi-sig