Add C++ autosummary extension

[jbms]

Fixes #92.

This is based on #116.

TODO:

• [ ] Document how to use separate build step to preprocess C++ input header using normal compiler
• [ ] Document how to extract compiler flags (especially include paths) from normal build process
• [ ] Add unit tests of api_parser
• [ ] Add unit tests of apigen
• [ ] Add example of explicit(bool) auto-conversion
• [ ] Support :order: option as in Python apigen
• [ ] Support equivalent of python_apigen_default_groups / python_apigen_default_order
• [ ] Support rST-style :group: and :relates: in addition to doxygen-style commands
• [ ] Support @-prefixed doxygen commands in addition to \-prefixed ones (e.g. @param in addition to \param)
• [ ] Add example of documenting multiple signatures together (by leaving no space between them)
• [ ] Add tests of source location (e.g. in signature, and in docstring)
• [ ] Add tests and documentation of NONITPICK

[jbms]

This is somewhat working, but perhaps we can work together to refine it.

[2bndy5]

documenting multiple signatures together (by leaving no space between them)

Is this related to overloads sharing the same docstring?

[jbms]

documenting multiple signatures together (by leaving no space between them)

Is this related to overloads sharing the same docstring?

Yes --- the result is a single cpp:function with multiple signatures.

I added an example of this: Array::operator[]

[jbms]

This is now updated to use types-clang rather than ones I generated myself. There are a few bugs in types-clang that required a cast as a workaround: https://github.com/tgockel/types-clang/pull/2

[2bndy5]

I also noticed that CursorKind.value isn't typed at all in that stub lib...

[2bndy5]

Going forward, can we change NONITPICK to NO_NIT_PICK? I keep reading it as NON_IT_PICK 🤣

[jbms]

Going forward, can we change NONITPICK to NO_NIT_PICK? I keep reading it as NON_IT_PICK rofl

Makes sense --- or could be: nowarnxref or something --- nitpick is a sphinx-specific term that may be confusing to readers of the C++ source code.

[2bndy5]

ok, I rebased this branch on latest main, and the CI is failing because it now tests for Windows and the fix for that is in my other branch (based on this one).

[jbms]

I wonder if we should merge this as an experimental feature, since this PR also contains the default-literal-role and highlight changes that also apply to Python and JSON.

[2bndy5]

We could do that. I've been think on ways to refactor this ext. My priorities are

1. better parsing mechanism
2. specify an entity via user friendly implementation

The database and diagnostics are a lesser priority for me. And I assume unit testing will just develop organically.

[jbms]

To be clear, by better parsing mechanism, is that in regards to the doxygen syntax, or in regards to the C++ source itself?

For specifying an entity, we could allow it to be specified by its "object name", e.g. foo::bar::Baz or foo::bar::Baz[overload_id] if overloaded. Much more reasonable than the clang USR. Allowing it to be specified by signature, e.g. as supported by the C++ domain for cross references, would be significantly more challenging I think.

[2bndy5]

To be clear, by better parsing mechanism, is that in regards to the doxygen syntax

Yes. I'm not sure how the C++ parsing would need improvement. I still want to provide a config option to turn off the doxygen syntax parsing, so the docstrings can be written in pure RST.

we could allow it to be specified by its "object name", e.g. foo::bar::Baz or foo::bar::Baz[overload_id] if overloaded

This was my thinking as well, but it would be more natural to use the parameter datatypes types for overloads (instead of a docstring specific ID). I find the ability to document multiple overloads with a single docstring very appealing - not even doxygen is capable of that.

[jbms]

To be clear, by better parsing mechanism, is that in regards to the doxygen syntax

Yes. I'm not sure how the C++ parsing would need improvement. I still want to provide a config option to turn off the doxygen syntax parsing, so the docstrings can be written in pure RST.

Sounds good.

we could allow it to be specified by its "object name", e.g. foo::bar::Baz or foo::bar::Baz[overload_id] if overloaded

This was my thinking as well, but it would be more natural to use the parameter datatypes types for overloads (instead of a docstring specific ID). I find the ability to document multiple overloads with a single docstring very appealing - not even doxygen is capable of that.

That could be done using the C++ domain symbol resolution used for cross-references, but is a bit tricky because currently the symbol tree only gets populated as the c++ domain directives are actually run, which is too late. We would need to somehow create a separate one and pre-populate it. I also think it is often inconvenient to specify the full signature if you have a lot of template or function parameters.

[2bndy5]

currently the symbol tree only gets populated as the c++ domain directives are actually run

I noticed that. Is there a reason you don't just save the parsed API to a builder env var (on a config-inited event)?

[jbms]

There wasn't a need for the symbol tree except for normal xrefs so I just tried to keep it working closely to how it normally does.

Note that the c++ domain symbol lookup is slow if you have a lot of symbols in the same namespace because it just does a linear search over every name --- it would be better if it used a dict.

[2bndy5]

Well I'm ok with this getting merged but there should be a warning on both config and demo doc pages. Possibly even a warning in the build log like you did for graphviz, but that seems a little excessive to me -- you went above and beyond my expectations there (again).

[2bndy5]

Instead of a task list in the thread OP, you could use a github project to track the progress of this extension.

[jbms]

I added a warning that it is experimental.

[2bndy5]

Did I mess up the rebase?

[jbms]

Did I mess up the rebase?

Not sure what happened with types-clang

[2bndy5]

I thought it was weird when the rebased push didn't trigger the CI (only RTD's CI ran).