[Mesa-dev] Mesa documentation (was: Gitlab migration)

[Eero Tamminen]

Hi,

On 23.05.2018 22:34, Jason Ekstrand wrote:
[...]> One of the motivations for doing this now is that there has been 
some
> desire to move the mesa website away from raw HTML and over to a 
> platform such as sphinx.  If we're going to do that, we need a system 
> for building the website whenever someone pushes to mesa.  The solution 
> that the fd.o admins would like us to use for that is the docker-based 
> gitlab CI.  Laura has been working on this the last couple of weeks and 
> the results are pretty nice looking so far.  You can check out a preview 
> here: https://mesa-test.freedesktop.org/intro.html

I looked at this, and noticed that few things seem out of date:

* Developers section doesn't list Igalia, and latest mentioned larger
   Intel contribution is for Mesa 7.9

* Acknowledgements section content seems to be from 90's

* Software drivers list misses SWR

* Conformance section blurb says:
-----
This file has the latest results of testing Mesa with the OpenGL 1.2 
conformance tests. Testing with the preliminary OpenGL 1.3 tests has 
also been done
-----

* Compiling and Installing section doesn't mention Meson,
   although there's separate sub section for it

* Bug database "The old bug database on SourceForge is no longer used."
   comment may be out of date

* Shading Language Support section "Contents" list is completely
   out of sync with the page content.  Aren't TOCs autogenerated?

* Open GL ES section:
   "Mesa implements OpenGL ES 1.1 and OpenGL ES 2.0"

* Performance Tips section should tell to use modern GL features
   instead of things like: "Try to maximize the amount of drawing
   done between glBegin/glEnd pairs."

* Application Issues section is out of date.  Maybe it could have
   a link to Mesa Git version of driconf, for a reference of applications
   for which Mesa needs workarounds?

If it's too much work to keep these up to date, maybe the obsolete
information could just be removed?


Also:

* Mesa/DRI Wiki item is a link.  It could be moved to Links section.

* Regarding "i945/i965 driver environment variables" subsection:
   - i945 -> i915 ?
   - i915 certainly doesn't implement all of the options that i965 does,
     so maybe it needs a separate section?
   - In the Sphinx generated lists it's hard to see what options
     are under what variables.  IMHO lists should use bullets to indicate
     hierarchy like the current documentation does:
	https://www.mesa3d.org/envvars.html


> Using sphinx gives 
> us all sorts of neat things like nice text formatting, syntax 
> highlighting, and autogenerated searchable navigation. Right now, it's 
> still using one of the standard sphinx themes so it looks a bit 
> "default" but that's something we can change.


	- Eero