[Mesa-dev] [RFC] - Rewrite mesa website in Sphinx

Jean Hertel jean.hertel at hotmail.com
Wed Apr 5 11:36:42 UTC 2017


Hello,


This is the second proposal for a rewrite of mesa website.


The last proposal have some problems (still available here: http://mesa.jeanhertel.com.br/):

  *   Use of big libraries like Twitter Bootstrap for the CSS;
  *   The design was focusing more on a blog-style instead of a documentation style;
  *   The rewrite was using Markdown, while there is already lots of documentation using reStructured Text;


This proposal tries to fix those issues.


Oficial repository: https://github.com/jlHertel/mesa-sphinx

Live demo: http://mesa2.jeanhertel.com.br/


As already pointed out, there was a conversion done some months ago by Nicholas Bishop. If you look carefully, you will note that my conversion is basically the same.


The point here is about other pieces of documentations that needs to be writen, or extracted from the source code.


I have readed some projects documentation (mainly in PHP) and the common case is to use tools like doxygen to generate an "API view" of classes, functions, etc.

And use the main website to write specific articles covering things not too obviously or to show some samples of usage.


To bring this approach to mesa, lets imagine an example with the GL Dispatch function.

In the main website (mesa3d.org) there is an article explaining exactly how the dispatcher works, why it was designed this way, and what advantages it can take on some operating systems and configurations.

In the API documentation site (that I imagine will be a sub-site under mesa3d.org) there will be the function/macro declarations for it.


Please, feel free to comment on this and suggest any other ideas.


Thanks in advance.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20170405/07d40113/attachment-0001.html>


More information about the mesa-dev mailing list