Hi Jean, On 6 March 2017 at 18:36, Jean Hertel <[email protected]> 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 _______________________________________________ mesa-dev mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/mesa-dev
