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 <[email protected]> To: [email protected] 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 _______________________________________________ Bf-committers mailing list [email protected] http://lists.blender.org/mailman/listinfo/bf-committers
