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

[Emil Velikov]

On 25 April 2017 at 19:56, Jean Hertel <jean.hertel at hotmail.com> wrote:
>>On 2017-04-24 12:40, Eric Engestrom wrote:
>>
>>Sorry I haven't had time to look at this until now.
>>
>>I just had a look, and besides style that can be tweaked later, I think
>>the main issue is that the homepage a visitor lands on when just typing
>>'mesa3d.org' should be more than a simple duplicate of the ToC.
>>
>>The 'recent releases' list we currently have gives at least that
>>information, and I would like to keep that until (if) we find something
>>else/better.
>
> OK, I've updated the demo site with this.
> Please visit: http://mesa2.jeanhertel.com.br
>
>>Another thing, can you please make a (rebasing) branch with a commit per
>>file converted, where the old file is deleted and the new created?
>>That way, it can be easily verified that the content was correctly
>>converted (no information lost; typo fixes and the like are ok) and more
>>importantly it makes it obvious at merge time that a file has been
>>changed in its html form, and the corresponding change can be made on
>>the rst file.
>
> Ok, I've done one commit per file change, see it here: https://github.com/jlHertel/mesa/tree/sphinx-docs
>
> Foot Note: Some changes are still necessary because some specification files
> (patents.txt, libGL.txt, features.txt, etc)
> need to be exported directly to the output folder.

Thanks again for doing this Jean. A handful of, mostly trivial, questions.

 - Is there a website where one can check the output of specific
Sphinx markdown.
 - Any ideas why the page contents are so narrow? It seems theme
related, doesn't it.
 - Personally I would not bother, yet, with the non-html documents.
These are quite picky to format correctly, as you've spotted already.
 - The Gallium and NIR documentation might be better suited in the toctree.
 - Maybe apply something like the following to the release notes
s|Mesa X Release Notes / $date|Overview\n\nRelease date: $date|

Eric,
Not sure that squashing  200+ changes (resulting in a total of +37K
-41K change stat) in one big blob is a wise move.
Since those are going to be pushed at once, there should be
limited-to-no side effects to mesa3d.org. Or perhaps there's another
reason why we'd want the lot squashed?

Thanks
Emil