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

[Emil Velikov]

Hi Jean,

On 6 March 2017 at 18:36, Jean Hertel <jean.hertel at hotmail.com> wrote:
> Hello guys,
>
>
> I want to propose a port of the current HTML documentation to a
> markdown-like syntax.
>
>
> Current problems
>
>
> Right now I see some problems with the approach used.
>
> People maintaining the documentation must know basic HTML syntax;
> There is no easy way to add a new release page;
>
> You need to open the index file and make changes there;
> You need to make a new file that will say what has been changed;
> You need to remember to update the release notes pages;
>
> The current website has many HTML tags not being closed;
> The website don't fit well in mobile area. (The layout is not responsive);
> Making any change to the layout is very hard, because you need to rewrite
> many pages;
> The current website doesn't show all the possibilities of the library. The
> website has a 1990 layout, and I think having a new layout would benefit the
> project;
>
> Proposal for Markdown
>
> Rewriting the documentation in a markdown syntax can bring some benefits to
> the development, like:
>
> Anyone writing for freedesktop.org, StackOverflow and Github already knows
> the markdown syntax.
> Independence of HTML. The developer don't need to worry if the HTML output
> will be correct. The generator makes all the translation from markdown to
> HTML;
> Easily change the layout of the site, simply changing the theme; (I don't
> think you change the layout much, but allowing it to be easy wont hurt)
> Creating a new release post can be maded easy, using some static site
> generator, for example, pelican;
>
>
> Right now I have maded a partial port from HTML to Markdown.
>
> The code can be found here: https://github.com/jlHertel/mesa-pelican
>
> I'm using the pelican static site generator with a layout ported from
> Wordpress using Twitter Bootstrap CSS.
>
> A live preview can be found here: http://mesa.jeanhertel.com.br/
>
>
> The static site generator tool and the theme used can be ignored if you
> want, the point here is to rewrite the documentation in a way that is easy
> to maintain and that don't need a good knowledge in HTML.
>
>
> Please leave your comments on the proposal.
>
>
Not sure if I agree with some of your points, then again i don't need
any - I'm already sold ;-)
Thanks you very much !

A couple of questions:
 - Some people have suggested Sphinx - are you familiar with it, do
you know similar tools for it ?
 - How did you convert the existing pages, are there any plans on
doing the rest ?
 - Do we need the clunky Bootstrap/jQuert JS ?

-Emil