astropy/astropy — pull request #218 by eteq (2012-05-01 09:13:34+00:00)
Title: Template for subpackage docs

This PR adds a template file for use when generating new subpackages (and hopefully, eventually, for homogenizing all of the subpackage documentation). It also re-writes ``config.rst`` as sort of a "case study" in how this template works.

Any thoughts on changes that should be made to this template?

One thing to note that was an arbitrary choice I made: This template assumes that any time you have multi-page documentation, the main page is in the ``docs`` directory, while only the sub-pages are inside a directory. E.g., if you have a subpackage named `mysubpkg`, with two sub-pages ``sub1.rst`` and ``sub2.rst``, the template assumes you would create the files ``docs/mysubpkg.rst``, ``docs/mysubpkg/sub1.rst``, and ``docs/mysubpkg/sub2.rst``. An alternative is to instead place the base document in the directory - e.g. the first file is instead ``docs/mysubpkg/mysubpkg.rst``.

I prefer the current way (the first example above), as it makes all the subpackage documentation have a base file in the same directory, so e.g. the main TOCtree in ``index.rst`` doesn't have to be altered if later someone adds subpages. But if anyone feels strongly about it, I can change this.