[Mesa-dev] Documenting with Sphinx

[Rob Clark]

On Tue, Dec 13, 2016 at 5: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. :-)

So, +100 to sphinx... I've been quite happy with it (and would be nice
to merge the NIR docs too while where at it).  Maybe someday we'll
have a "mesa book" after 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.

So as far as I understand on kernel side we are *somehow* extracting
out C comment docs and combining w/ sphinx stuff..  maybe there is
something to re-use from that.

BR,
-R