On Mon, Mar 1, 2010 at 5:52 PM, Sridhar Ratnakumar firstname.lastname@example.org wrote:
On 2010-03-01, at 8:44 AM, Sridhar Ratnakumar wrote:
Is the documentation directory expected to contain files in certain format - for example, with a file describing the Table-of-Contents (toc.xml) that would then be used to render MSDN like doc tree?
.. and/or make a single-container (eg: CHM) out of it. I guess this feature could be made optional, so developers can include simple docs without having to worry about any mandatory standard, and we could contribute a Sphinx patch to automatically produce toc.xml.
 ActivePython already includes extra docs (tutorials, peps. etc..) in a CHM file along with the Python docs
We didn't make any assumption on the documentation files format. But now that they will be described, you could create a distutils2 command that generates toc.xml on the fly by reading the list of doc files in the project (build_msn_doc?)
Another idea that come in my mind also for structurized doc is to use skeletons when the project is created in the first place. (that's also a good way to standardize how the community creates its packages)
Sean R. worked on a command called mkpkg that can be used to generate a distutlils2-based project. It asks a few questions then creates a setup.py file for you.
Maybe it could be extended to build a pre-generated Sphinx doc structure, or a CHM-like one. The difficulty is to provide something that can evolve on its own. Plugins maybe ?
Last, I think that this work could be reunited with the work done in Distribute's build_doc/upload_doc commands.