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