[Mesa-dev] Documenting with Sphinx

[Vedran Miletić]

On 12/13/2016 09:46 PM, Jason Ekstrand wrote:
> 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
> 

Somewhat related effort was already discussed several months ago:
https://lists.freedesktop.org/archives/mesa-dev/2016-September/128182.html

V.

-- 
Vedran Miletić
vedran.miletic.net