[Bf-committers] Python API Documentation

[Campbell Barton]

On Wed, Aug 18, 2010 at 9:01 AM, Stephen Swaney <sswaney at centurytel.net> wrote:
> On Mon, Aug 16, 2010 at 05:46:26PM +0200, neXyon wrote:
>> 2) Have a database with a nice structure to store docs
>>
>> Advantages:
>> * Easy to edit for everybody, there could be a web interface to edit
>> docs directly
>> * Lower binary size
>> Disadvantages:
>> * No docstrings, so no direct documentation in the interpreter, although
>> the help function could be overwritten to retrieve the docs from the DB
>
> Not having docstrings is a *major* drawback.  Not only are they expected
> to be there, they are one of the features that makes developing python
> code an enjoyable experience.
>
> --
> Stephen Swaney
> sswaney at centurytel.net

Firstly I'd like to postpone any big changed to the doc system for a
while (until 2.5 is more on track).

While the current system is a bit strange its very easy to maintain
for me with a single script that extracts docs and builds the API
reference.

If docs in blenders source becomes a problem I'm open to having them
stored externally and use a "class.attr" key to retrieve them for
tooltips and python.

Its probably possible to get these external docstrings from the python
api dynamically. examples of how it could work.
- for builtin types getattr can check for "__doc__" and return an
external string.
- rna functions can can have their own "__doc__" getattr too.
- C methods are not so easy since thir docs are defined on creation
but we could re-assign string like objects after PyType_Ready is
called which access the full description when __str__ is called on
them.
- class.__dict__ could use a dict subclass which intercepts __doc__
too, I rather not do this but just pointing it out as a possible way
to dynamically provide docs. Currently a dict-subclass is used with
operators so properties are shown in the order they are defined.