On Tue, Dec 13, 2016 at 2:47 PM, Eric Anholt <e...@anholt.net> wrote:
> Jason Ekstrand <ja...@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.
_______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/mesa-dev
