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

[Emil Velikov]

On 5 April 2017 at 12:36, Jean Hertel <jean.hertel at hotmail.com> wrote:
> 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.
>
Thanks for the update Jean.

I'm a huge fan of this since we can have all the documentation with
consistent look and in one place.
Plus if we get tired of the RTD look we can easily change the theme or
write our own ;-)

Personally I think the only thing that's missing is the News
(index.html) page and with that we can all the lot.
As you mentioned there's a few places where things can be
improved/rewritten but that can follow in due time.

Thanks again
Emil