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

[Eric Engestrom]

On Tuesday, 2017-04-25 18:56:53 +0000, Jean Hertel 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

Perfect, thanks!
I left a couple comments on 0658cf3db95c77dbe590.

> 
> >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

Yup, that's exactly what I had in mind :)

I left a comment on d88398cf8fc0588e7afd, but what I've seen of the rest
looks good to me.

Now we "just" need to review every single file to make sure everything's OK.
I suggest everyone who reviews a few file leaves a reply to this mail with
the list of file they reviewed and their r-b, or directly on the github
commits for each file. I'll add those r-b's to each commit when merging.

The list of commits can be easily seen on this page:
https://github.com/jlHertel/mesa/compare/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.

I see you added a commit since your email (922e597521833875c9e5), which
essentially exports all these files to the website.
I'd argue most (if not all) of these files only make sense in the repo,
not on the website, so I think that commit can be dropped.

I suggest you fix any issue from now on with `--fixup` commits (I'm
taking back my rebasing suggestion), and I'll squash those when merging.
This way, comments left on github commits won't be lost by rebasing.

I'll also squash your 3 "fix issue with sphinx-generator" with their
respective file commits.

Anyone looking for a next step, a few ideas:
- integrate the gallium & nir docs
- add overview documentation for each module
- add sphinx comments in the code, pull these into module pages
	(functions, structs, enums, etc.).
- reach the DRM kerneldocs-level of documentation [1]
- ???
- profit!

Cheers,
  Eric

[1] https://dri.freedesktop.org/docs/drm/gpu/index.html