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

[Rhys Kidd]

On 27 August 2016 at 01:09, Nicholas Bishop <nbishop at neverware.com> wrote:

> Hi,
>
> I'd like to propose a conversion of Mesa's documentation to
> reStructuredText (RST) and hosting the result on readthedocs.org. The
> intent is to make Mesa's documentation more accessible, searchable, and
> easier to edit.
>
> I put together a quick proof-of-concept here:
>
>     http://mesa-docs.readthedocs.io/en/latest/intro.html
>
>     (For comparison: http://mesa3d.org/intro.html)
>
> Readthedocs.org essentially renders either Markdown or RST from a git
> repository (or other VCS) into a nice pretty set of HTML pages. (I'm more
> familiar with Markdown than RST, but I saw the Gallium docs are already
> using RST on readthedocs.org.)
>
> Putting the content in RST and on readthedocs.org makes formatting and
> searching easy, and it's a familiar platform for many developers.
>
> For the linked proof-of-concept I used pandoc (http://pandoc.org/) to
> convert all the HTML pages to RST, on top of which I did some minor editing
> to make the table of contents look reasonable. It's by no means a finished
> conversion, but I hope having something to look at can make discussion
> easier. This is all just a few hours work, but of course proofing and
> correcting all the text/formatting would take somewhat longer.
>
> Here's the git repo that readthedocs.org is pulling from:
> https://github.com/nicholasbishop/mesa-docs/tree/master/docs
>
> Thoughts?
>

Hello Nicholas,

Although not a core Mesa developer, I have recently done work on Mesa
documentation.

So FWIW, in my view this is a worthwhile objective to work towards
readthedocs.org formatted documentation. It is clear and well presented. We
also have precedence within this project for using that service, for the
Gallium docs in RST.

Worth considering however:

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).
2. How easy it is to automate the additional tweaks you mention? Scriptable?

Rhys


>
> -Nicholas
>
>
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/mesa-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20160911/98b7a382/attachment.html>