API Docs build adjustment.

[mwichmann]

For a "package" which has a main piece and submodules, the main part is now processed before, rather than after, the submodules. Usually there's introductory material (e.g. in the main module's docstring) and it's more useful for this to appear at the top of a package's page rather than down after all the submodules.

Made some docstring tweaks in two modules where the result didn't look very good - Debug and PathList. For PathList, Sphinx doesn't process both a class docstring and its __init__ method's docstring - you get one or the other, so joined those together.

Doc-only change (and mostly, changes to the build of the doc, not so much contents), code and tests are not affected.

Contributor Checklist:

• [ ] I have created a new test or updated the unit tests to cover the new/changed functionality.
• [X] I have updated CHANGES.txt (and read the README.rst)
• [X] I have updated the appropriate documentation