[Mesa-dev] Documenting with Sphinx

[Jason Ekstrand]

On Dec 15, 2016 6:40 AM, "Jani Nikula" <jani.nikula at linux.intel.com> wrote:

On Thu, 15 Dec 2016, Robert Bragg <robert at sixbynine.org> wrote:
> On Wed, Dec 14, 2016 at 7:17 PM, Jani Nikula
> <jani.nikula at linux.intel.com> wrote:
>> On Wed, 14 Dec 2016, Robert Bragg <robert at sixbynine.org> wrote:
>> The AST does include comments right above each cursor, but it falls
>> short for comments not attached to cursors. You have to walk the tokens
>> for that. I think I have most of this solved, though it hasn't seen much
>> testing.
>
> Right, what I was thinking of though is that clang itself can actually
> parse doxygen style comment sections like \brief, \param and \returns:
>
> http://clang.llvm.org/doxygen/classclang_1_1comments_1_1Parser.html
>
> Seems a bit mad, but this e.g. helps enable a -Wdocumentation warning
> to check \params match actual function arguments
>
> I was wondering if that can somehow be exposed via the AST accessible
> through the python bindings.

AFAICT this is not available via libclang or its python bindings; you
can only get at the \brief paragraph, which does seems to indicate some
parsing under the hood. I don't know if the information is available via
some other clang interface, but even if it is, venturing outside of what
python-clang provides makes both writing the tool and interfacing with
Sphinx an order of magnitude more painful.

Obviously -Wdocumentation working out of the box is nice, but apparently
you'd have to use Doxygen anyway. Personally, I'm not interested in
Doxygen compatibility or format. If you want that, you should probably
use Doxygen.

Oh, there's also cldoc [1], a documentation generator based on
python-clang, but that invents another markdown based comment format and
produces XML, neither of which work that great with Sphinx.

I've looked at all of this before, and for *my* needs, aiming at a
minimal python-clang based comment extractor that's mostly passthrough
with some Sphinx C Domain directives sprinkled on top is the right
choice. Kind of like autodoc for C, with no format conversions in
between. And this is, of course, taking Sphinx for granted. Maybe even
that is still open for you.


Dylan and I talked about a couple of possibilities for how to tie things
into sphinx.  One was to come up with some regex and do a mass conversion
of the tree from doxygen to sphinx rst. Another was use that same regex as
a filter that gets applied as you pull from the source.  I think we'll have
to do since experimentation to figure out the best approach.  Right now,
Mesa doesn't really make full use of doxygen so regex is probably tractable.

We've also talked about some of the doxygen-based solutions such as
breathe.  Personally, though, I'd rather get rid of the middle man.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20161215/4b4c2774/attachment.html>