Code review comment for lp:~fwereade/pyjuju/fix-docstrings

> Minor nits: when using singlehtml, links to source do not work.

AFAICT, that's a Sphinx issue, sadly. I've (somewhat nastily...) disabled the viewcode extension for singlehtml builds.

> Also, the
> headings in that view really don't work well with the size of the left column.
> Maybe in general we would want to collapse the headings to the second level of
> the package namespace, under ensemble, that is just ensemble.agents instead of
> also seeing ensemble.agents.base, ensemble.agents.dummy, etc.

IMO batching all docs at the second level is too much -- you certainly don't want all of ensemble.providers in a single file (do you? maybe I'm missing context). I strongly favour batching them up in exactly the same way we do the source code -- by choosing module boundaries, we've implicitly chosen a "sensible" chunking for the concepts in play, and if there's a problem with those divisions we should be rearranging the code rather than the documentation. IMO ;).

Given the undeniable ugliness, though, module titles are now abbreviated as follows (approximately inspired by twisted's documentation):

ensemble -> ensemble
ensemble.providers -> ensemble.providers
ensemble.providers.orchestra -> e.providers.orchestra
ensemble.providers.orchestra.cobbler -> e.p.orchestra.cobbler

I think it's a reasonable tradeoff: you're unlikely to get lost with two unabbreviated names' worth of context, and while titles still sometimes overflow the sidebar, it's only by a few chars.