maas-devel team mailing list archive

[Gavin Panella <gavin.panella@xxxxxxxxxxxxx>]

I did some work on the way home from Nuremberg to convert MAAS's
documentation to Markdown [1], following many of the conventions that
Juju uses for its docs [2][3].

It was a bit more involved than I expected, but `pandoc` took a lot of
the pain away, though some clean-up of its automated conversion will
probably be necessary.

One of the biggest problems is that the docs don't render in a "pretty"
state, so it's hard to review changes. In fact, `markdown_py` renders
only page fragments, not whole HTML pages, so rendering static docs
requires an additional step. In Juju this is done via a Cheetah
template. That seems fine to me for MAAS, to stay close to Juju's
approach [3].

However, it would also be good to render these docs into MAAS's UI, so
that the reference manual always ships with MAAS. We probably would not
need the full-page template for that; we wouldn't need to use a Cheetah
template in the running application, only at build time.

To be honest, to us developers, switching to Markdown isn't much of a
win. There's work needed to migrate, and we lose things that Sphinx
gives us, like warnings about dangling links and documents. However, the
win is probably to be found in reducing friction for contributors — I'm
thinking of Nick right now.

(I'd like to put in a word for Mallard [4] right now. It's the closest
thing to software documentation nirvana yet created, probably.)

My branch [1] is a work in progress. It's not landable as is. I may
return to it at some point, but if someone else gets this task, perhaps
they'll want to continue my work, or crib from it.

Gavin.


[1] https://code.launchpad.net/~allenap/maas/markdownify/+merge/256718
[2] https://jujucharms.com/docs/stable/contributing
[3] https://github.com/juju/docs
[4] http://projectmallard.org/