<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, Dec 13, 2016 at 2:47 PM, Eric Anholt <span dir="ltr"><<a href="mailto:eric@anholt.net" target="_blank">eric@anholt.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">Jason Ekstrand <<a href="mailto:jason@jlekstrand.net">jason@jlekstrand.net</a>> writes:<br>
<br>
> Hey All,<br>
> I don't figure this will be terribly controversial (I'm about to be wrong,<br>
> aren't I?) but how do people feel about switching our "primary"<br>
> documentation focus, as far as we have one, to sphinx?  Right now, Gallium<br>
> uses sphinx for documenting all of it's "public" interfaces.  A while ago,<br>
> Connor wrote some nice NIR documentation using sphinx that never got<br>
> merged.  I've also spent some time this year and written some additional<br>
> documentation about Intel surface layout that I'd like to have a place to<br>
> put.  The thing that's in common with each of these is that they contain<br>
> quite a bit of prose about the general theory of how things work and not<br>
> just code comments so sphinx seems like a fairly good fit.  There are also<br>
> some sort-of "architectural" things in the Vulkan driver that I would like<br>
> to document better and we don't have a good place for that right now.<br>
><br>
> Here's what I have in mind:<br>
><br>
> Each component that we care to document (this may not be everything!) would<br>
> have a docs/ or sphinx/ folder.  In that folder would be any side-band (not<br>
> in code comments) documentation.  We would also set up some sort of<br>
> source-scraping tool to turn inline comments into sphinx documentation.  At<br>
> the component maintainer's discretion, that code could either be imported<br>
> into sphinx whole-sale or curated by importing bits into other<br>
> documentation files in a more carefully curated manner.  Of course, a<br>
> maintainer could also choose to do all of their documentation side-band<br>
> (sphinx allows for this) or to not document at all. :-)<br>
<br>
</span>I've written doxygen-style comments in my code for a long time, but<br>
never really looked at the doxygen output, so I wouldn't say I'm wedded<br>
to doxygen.  I think some side-band docs for architectural descriptions<br>
(like NIR needs) would be great, and if sphinx would help with<br>
encouraging those to be written and merged, then that's pretty good with<br>
me.<br></blockquote><div><br></div><div>I think many of us have. :-)<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I'm a little skeptical of sphinx due to not being able to extract docs<br>
>From C comments in code in the base tool.  Apparently Breathe can chain<br>
doxygen into sphinx, so hopefully a "let's get excited about sphinx"<br>
patch series would convert our doxygen-based docs generation to using<br>
that.<br>
</blockquote></div><br></div><div class="gmail_extra">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.<br></div></div>