On Tuesday, December 13, 2016 2:47:27 PM PST Eric Anholt 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.
Agreed. I've used Doxygen in large C++ projects, and it was very helpful there in order to understand the class hierarchy and look up various API interfaces. But I've never actually used it in Mesa. I took a look once, and it didn't seem terribly useful. Sphinx seems to work pretty well for architectural documentation, and we could definitely use more of that in Mesa. Having a high level overview of how the pieces fit together is really helpful. Once you know where to look, the code is pretty well commented and readable.
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/mesa-dev
