On Feb 27, 2013, at 02:33 PM, Chris Cargile wrote:
the Moin system will get us away from the Atlassian licensing hassle AND would tie in great for enabling a new website for the MM3 release,
I'm really hoping we can get onto Moin soon, not only for the above good reasons, but also because of the free software issue, and because -- while generous -- it's still a big hassle to deal with our Confluence hosting provider when problems come up. I'm very confident we can find a Moin-based wiki a good home.
The documentation is maintained to some level in Atlassian, pythonhosted.org, and the bzr repos (, other places?) per package, so Terri explained that Atlassian is the main location for how-to's, admin guides, and GSOC stuff. Otherwise, for simplicity, the packages have docs and doctests, in the individual package themselves
I'm a big fan of having as much documentation in the source repository as possible. I love a good wiki, but everything needs gardening and documentation seems better suited for version control systems. Not all documentation need be testable, but that which can be works great being part of the source tree. (The current doctest suite is I think of mixed quality; some of the older doctests conflated too much bad-path testing which makes it more difficult to read as documentation. I've been migrating much of that to unittests, in order to improve the readability and good-path flow of the documentation.)
It's also much easier to review and merge documentation changes via our dvcs tools.
One thing that's missing is better overview documentation. That's long been on my list of things to improve.
Would the merges accepted propogate document changes to the package repos or are we referring to a merge against a documents-repo that is somewhere I don't know of. I'm still confused on where the sphinx documentation plays into it (is that maybe like building javadocs only, instead it does so for python, maybe)
The pythonhosted.org (formerly packages.python.org) documentation is generated
from the source tree via python setup.py build_sphinx. You can build it and
view it locally the same way. python setup.py upload_docs is what gets the
new documentation uploaded, but I've just created a project on readthedocs.org
so I think we should migrate there as our primary online documentation
source. The nice thing is that gets automatically updated when we push
updates to lp:mailman (i.e. trunk).
Cheers, -Barry