On 12/13/2016 09:46 PM, Jason Ekstrand wrote: > 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. :-) > > How do people feel about this? > > How attached are developers to the current doxygen setup? Some of the > sphinx source-scraping tools require running doxygen first and then they > scrape the doxygen. If we're going to use one of these, we may end up > wanting a different doxygen config for usage with sphinx and I'm > wondering if we should try and preserve what's already there. > > --Jason >
Somewhat related effort was already discussed several months ago: https://lists.freedesktop.org/archives/mesa-dev/2016-September/128182.html V. -- Vedran Miletić vedran.miletic.net _______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/mesa-dev
