[Mesa-dev] Documenting with Sphinx

[Jason Ekstrand]

Hey All,
I don't figure this will be terribly controversial (I'm about to be wrong,
aren't I?) but how do people feel about switching our "primary"
documentation focus, as far as we have one, to sphinx?  Right now, Gallium
uses sphinx for documenting all of it's "public" interfaces.  A while ago,
Connor wrote some nice NIR documentation using sphinx that never got
merged.  I've also spent some time this year and written some additional
documentation about Intel surface layout that I'd like to have a place to
put.  The thing that's in common with each of these is that they contain
quite a bit of prose about the general theory of how things work and not
just code comments so sphinx seems like a fairly good fit.  There are also
some sort-of "architectural" things in the Vulkan driver that I would like
to document better and we don't have a good place for that right now.

Here's what I have in mind:

Each component that we care to document (this may not be everything!) would
have a docs/ or sphinx/ folder.  In that folder would be any side-band (not
in code comments) documentation.  We would also set up some sort of
source-scraping tool to turn inline comments into sphinx documentation.  At
the component maintainer's discretion, that code could either be imported
into sphinx whole-sale or curated by importing bits into other
documentation files in a more carefully curated manner.  Of course, a
maintainer could also choose to do all of their documentation side-band
(sphinx allows for this) or to not document at all. :-)

How do people feel about this?

How attached are developers to the current doxygen setup?  Some of the
sphinx source-scraping tools require running doxygen first and then they
scrape the doxygen.  If we're going to use one of these, we may end up
wanting a different doxygen config for usage with sphinx and I'm wondering
if we should try and preserve what's already there.

--Jason
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20161213/fcd46a6a/attachment.html>