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

[Jean Hertel]

Hello Emil,

> Some people have suggested Sphinx - are you familiar with it, do you know similar tools for it ?
I really don't know Sphinx.
From what I have readed (In wikipedia) it basically converts reStructured Text to HTML.
Of course Pelican can do this too.
But I think markdown is more widely adopted.


> How did you convert the existing pages, are there any plans on doing the rest ?
The conversion is done by hand. This is why I know there are some HTML tags not being closed.
The plan for conversion is when I have free time, my expectation is to have the remaining NEWS converted until 12/03.


> Do we need the clunky Bootstrap/jQuert JS ?
I have used both jQuery and Bootstrap because of the already done testing/large adoption. The tools are very big, unfortunately :(
Of course any layout is possible, so the answer for your question is: We can make whatever is wanted, but then, we need to test very carefully on a wide range of displays and browsers do ensure the good is good and don't break. Unfortunately my knowledge in the area of responsive design is somewhat limited.

What comes to my mind right now is the use of a CDN (https://en.wikipedia.org/wiki/Content_delivery_network) to ease the server load. For this, we need only someone to provide us one. As an open source project, I don't really see this as a problem. Maybe asking Google and using their CDNs.


Best Regards

Jean Hertel

Em 06-03-2017 18:35, Emil Velikov escreveu:

Hi Jean,

On 6 March 2017 at 18:36, Jean Hertel <jean.hertel at hotmail.com><mailto: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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20170306/f029b98d/attachment.html>