[Mesa-dev] Documenting with Sphinx

[Dylan Baker]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: signature
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20161213/5f43d249/attachment.sig>