grrr my attachment was stripped
here it is inline..
Campbell Barton wrote:
Campbell Barton wrote:
Author: campbellbarton Date: 2007-07-02 14:22:30 +0200 (Mon, 02 Jul 2007)
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 Bfemail@example.com http://lists.blender.org/mailman/listinfo/bf-python