[Mesa-dev] Documenting with Sphinx

[Eric Anholt]

Jason Ekstrand <jason at jlekstrand.net> writes:

> 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. :-)

I've written doxygen-style comments in my code for a long time, but
never really looked at the doxygen output, so I wouldn't say I'm wedded
to doxygen.  I think some side-band docs for architectural descriptions
(like NIR needs) would be great, and if sphinx would help with
encouraging those to be written and merged, then that's pretty good with
me.

I'm a little skeptical of sphinx due to not being able to extract docs
From C comments in code in the base tool.  Apparently Breathe can chain
doxygen into sphinx, so hopefully a "let's get excited about sphinx"
patch series would convert our doxygen-based docs generation to using
that.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 832 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20161213/182ea200/attachment.sig>