[Mesa-dev] Documenting with Sphinx

[Jason Ekstrand]

On Tue, Dec 13, 2016 at 2:47 PM, Eric Anholt <eric at anholt.net> wrote:

> 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 think many of us have. :-)


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

I've experimented with breathe a bit for this at one point.  The main
problem I had was that it was slow.  However, I think we can probably make
it more efficient if we tweak the doxygen config to be less verbose.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20161213/d45e3dcd/attachment.html>