[Bf-committers] Python API Documentation

[Roger Wickes]

to my feeble mind, api docs are programmer docs and +1 for docstrings. 

User docs would be like a wiki tutorial or such as we now have structure for; a
book that ties multiple api calls into a cohesive task, like creating a chart. 

so docs on individual api calls should go with the code. If a py programmer 
finds an error, or wants
to add to an api doc, submitting a patch is rock simple. Everyone has svn (read) 
access and
is free to submit patches for review (I would suppose by Campbell/you). 

 --Roger


----- Original Message ----

From: neXyon <nexyon at gmail.com>
To: bf-committers at blender.org
Sent: Mon, August 16, 2010 11:46:26 AM
Subject: [Bf-committers] Python API Documentation

  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