[Mesa-dev] Proposal: move the Mesa documentation to readthedocs.org

[Nicholas Bishop]

Good questions,

> 1. How can we minimize the effort of maintaining two repositories? (I don't
> think anyone here would support dropping the HTML docs, as they feed into
> the main Mesa website).

I agree that maintaining two repos would be bad, but we don't need to
do that. Sphinx can generate HTML from RST in combination with a style
template to provide the look 'n feel. This is what Read The Docs does:
http://docs.readthedocs.io/en/latest/builds.html#sphinx

For Mesa's website we could either pre-generate the HTML and store it
in the mesa git repo alongside the RST sources, or it could be done in
a separate update-the-website script. I'm not sure how Mesa's website
is currently deployed.

> 2. How easy it is to automate the additional tweaks you mention? Scriptable?

Assuming that RST becomes the canonical source for the HTML it'll be a
one time deal; we use pandoc to automate the initial conversion as
shown in my github repo, then manually fix any formatting issues. I'm
not sure how long it would take, but I'm happy to take on that work if
there's buy-in from the project maintainers.

-Nicholas