[Mesa-dev] NIR documentation

[Connor Abbott]

Hi,

Over the past few weeks or so, I've been sitting down and writing some
documentation on how NIR, and especially the core NIR datastructures,
works. At this point I think it's reasonably complete, although I've
probably forgotten something that I should mention, and one thing
that's missing for certain is a description of what the various
lowering, optimization, and analysis passes do (although some of the
motivation is covered in the documentation for other things). I could
probably keep adding minor things to it, but at this point I think
it's probably just better to put it out there. I haven't bothered to
submit a patch, since it's probably easier to read the end-result than
the source, although I've made a branch available at:

git://people.freedesktop.org/~cwabbott0/mesa nir-docs

and I've got a mirror of the generated output at:

http://people.freedesktop.org/~cwabbott0/nir-docs/

It's using Sphinx, which I chose since Rob said it worked well for
him, and we have a similar use-case (mostly lots and lots of graphs,
plus maybe a few equations and lots of text). The generated pdf is
*mostly* ok, although I'm not really concerned about the rough edges
-- just having an HTML page is enough for me. I'd like to put it on
readthedocs.org, but for some reason it's not working for me since it
seems to pick up the Gallium documentation despite pointing it to
NIR's and then the page where it's supposed to go gives me a 404.

The intention is to merge this soon, and then when changing the parts
of NIR that the docs refer to, it's on the author to update the docs.
Of course, there's always the fear of the docs going stale, but I've
tried to make it more about high-level information that you can't find
in the source. Hopefully, if you're thinking about changing something
fundamental about how NIR works, then the process of writing
documentation will help you think through the change.

This is supposed to help people get up to speed on NIR, especially
some of trickier parts of it like control flow, so if you're someone
who learned it and found some parts confusing that aren't yet covered,
then that would be very helpful.

Connor