[capi-sig] Documenting a C/Py API
cbarton at metavr.com
Tue Jul 3 04:14:50 CEST 2007
Martin Poirier wrote:
> --- Carsten Haese <carsten at uniqsys.com> wrote:
>> On Mon, 2007-07-02 at 23:30 +1000, Campbell Barton
>>> However Id be interested to know how other
>> projects deal with the issue
>>> of maintaining docstrings and online docs.
>> I maintain separate docstrings and online docs for
>> one simple reason:
>> The online docs can be more extensive than
>> docstrings. Docstrings are
>> for brief memory-joggers. Online documentation can
>> contain examples and
>> generally more detail that's not appropriate for
> Can you elaborate on this a bit. What kind of tools do
> you use to generate/maintain your docs?
> - Blender developer
Its just one script that runs inside blender and writes its docstrings
to py files epydoc can use.
At the moment it just takes a PyType, and writes a file with its methods
and attributes. adding indenting and method names to the epydocs.
I wrote this last night and it only works with the Group and Camera
types, so if we choose to keep using this method we can extend and
modify as needed.
Barry pointed out that docs could be generated with epydoc inspecting
the C api directly,
Id be interested to know if you had much epydoc spesific stuff in these
docstrings, though i was aware this was possible in some cases, you end
up with nicer docs if they include formatting tags.
Carsten, agree Examples within the C docstrings is bloating them too
much, Id like to add these in when generating the py files with some
form of #include that inserts an existing Py file.
Thanks for your feedback - I may be over reacting about maintaining 2
sets of docstrings because when I first started with Blenders Python api
there would be for instance..
And each needed a docstring and epydoc, so we had to have 6 different
bits of documentation for each setting. We have decided not to use
get/set style anymore so its only 2 - which may be a necessary annoyance
and not that bad in practice.
This is the biggest PyType we have, to get an idea of what Im talking
More information about the capi-sig