[Bf-committers] Python API Documentation

[neXyon]

  Hi all!

During my GSoC project which I just merged, I implemented a new Python 
API documentation system that uses templating and gets documentation out 
of several different sources to unify them then by writing out Sphinx 
.rst files that can then be used to build an html or latex documentation 
with sphinx-build.

The problem (in my eyes) we have is the many different locations of 
documentation we have at the moment, if you look at 
source/blender/python/doc/sphinx_doc_gen.py you'll find out that it gets 
the documentation from three different places:

* bpy.types and bpy.operators are generated using the rna_info module
* the bge modules are handwritten rst files
* the other currently online modules are generated using the python 
docstrings
* there are still some modules like bgl that still aren't in the online 
documentation yet

Now there should be a unified solution and I have two possible solutions:

1) Have all documentation as docstrings:

Advantages:
* Docstrings can be read in the interactive console
* The documentation can be kept very near to the code
Disadvantages:
* They blow up binary size as for C modules all docstrings are in the binary
* They are not as easy to maintain and edit by dedicated documenters 
that are no blender coders with svn access

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
* Documentation and code are seperated, extra validation is needed to 
check completeness of the docs

Let the discussion begin. :)

Regards,
neXyon