[Bf-committers] Python API Documentation
Roger Wickes
rogerwickes at yahoo.com
Tue Aug 17 04:27:59 CEST 2010
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
More information about the Bf-committers
mailing list