[Mesa-dev] [Request for Comments] - Port documentation to Markdown

[Jean Hertel]

Jason,


First, thanks for pointing the other attempts of doing all that.

Reading those links and the responses in this thread my current opinion is:

  *   The developers want a place to put more documentation;
  *   Large CSS portions are not desired, so a very simple CSS is needed for better maintenance. (No Twitter Bootstrap allowed);
  *   Sphinx is preferred, as there is already some documentation written in it. (Gallium and NIR);

If you look carefully, right now the mesa website is splited in 3 main parts:

  *   New releases announces; (Those are mainly writed by Emil);
  *   Basic Helping and Debugging (Mailing lists, writing for Mesa, bug reporting, etc);
  *   Some Basic documentation on Mesa itself (Mesa Dispatch, Off-screen rendering, EnvVars, etc);


Given these points, is clear to me that a Sphinx approach is much more valuable.

I will try to understand it and write a new proposal for the website, along with the documentation.


Cheers,

Jean Hertel

________________________________
De: Jason Ekstrand <jason at jlekstrand.net>
Enviado: terça-feira, 7 de março de 2017 18:47
Para: Jean Hertel
Cc: Eric Engestrom; mesa-dev at lists.freedesktop.org
Assunto: Re: [Mesa-dev] [Request for Comments] - Port documentation to Markdown

Hey Jean,

First off, it's worth throwing out there that this is not the first proposal to do something like this, just the proposal with the prettiest demo :-)  A few references for you:

https://lists.freedesktop.org/archives/mesa-dev/2016-August/127178.html
https://lists.freedesktop.org/archives/mesa-dev/2015-June/085786.html
https://lists.freedesktop.org/archives/mesa-dev/2016-December/138196.html

In particular, the conversion of the entire mesa website to rst has already been done... twice.

One thing that I would personally like to see is for us to start building some Sphinx-based architecture-level documentation for mesa.  There is already some substantial gallium documentation written using RST and Sphinx and I have some pretty good chunks of NIR and ISL documentation floating around that I'd like to merge at some point but there's no good place to put it at the moment.  Whether this sort of documentation ties into the website or is its own thing that developers just build from the git tree, I don't care too much.  However, given the way Sphinx is designed, just doing everything in Sphinx seems like a reasonable thing to do.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20170308/dcfa2be2/attachment.html>