Martin Poirier wrote:
--- Carsten Haese carsten@uniqsys.com wrote:
On Mon, 2007-07-02 at 23:30 +1000, Campbell Barton wrote:
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 docstrings.
Can you elaborate on this a bit. What kind of tools do you use to generate/maintain your docs?
Martin
- Blender developer
Its just one script that runs inside blender and writes its docstrings to py files epydoc can use.
http://projects.blender.org/plugins/scmsvn/viewcvs.php/branches/pyapi_devel/...
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.. mesh.getName() mesh.setName() mesh.name
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 about...
file:///cvs_blender/blender/source/blender/python/api2_2x/doc/BPY_API/Object.Object-class.html