[Mailman-Developers] background on maintaining the documentation (was RE: Mailman-Developers Digest, Vol 286, Issue 9)

[Barry Warsaw]

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