[Distutils] layout and setup.py for packaging documentation

[Tarek Ziadé]

On Mon, Mar 1, 2010 at 5:52 PM, Sridhar Ratnakumar
<sridharr at activestate.com> 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[1]) 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.
>
> -srid
>
> ***
> [1] 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.

Regards
Tarek

-- 
Tarek Ziadé | http://ziade.org