Quoting Jason Ekstrand (2016-12-13 12:46:17) > 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 >
As a follow up question, if we do decide to convert the documentation to sphinx, how would people feel about converting the content of $MESA/docs (the html pages) to sphinx as well? I am volunteering to do this work, in case anyone is wondering. Dylan
signature.asc
Description: signature
_______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/mesa-dev
