Better C++ support in the sphinx-immaterial theme

[2bndy5]

I've been helping develop the sphinx-immaterial theme (ported from mkdocs-material theme), and there's new extensions/features available with the theme; some of which are C++ specific.

clang-format

The sphinx_immaterial.apidoc.format_signatures extension will format C++ signatures with clang-format using the provided style (which can be different for the various syntax/languages that clang-format supports).

Instead of using this extension, the theme also provides a limited CSS styling for multi-lined signatures. Any signature that is longer than a specified length of characters (default is 68) is considered a multi-line signature.

cross-linking parameters

The sphinx-immaterial theme also does automatic cross-linking of parameters found in a signature with the corresponding description (made with :param: field). Parameters will also be added to the ToC with field description names (like "Parameters", "Returns", "Throws", etc), but the that can be turned off. More info on that in the general API improvements/customization doc.

This feature will also warn doc maintainers about parameters that have descriptions but are not found in the corresponding signature. This is great for typos in described parameters' names.

references to cppreference.com

The sphinx_immaterial.apidoc.cpp.cppreference extension will automatically link C++ keywords/datatypes found in signatures to the equivalent definition found at cppreference.com. You can improve this by editing the XML files that the extension uses as a map.

The sphinx-immaterial theme also checks the C domain definitions for unresolved references. This provides users a way of cross-referencing C macros when used as default values in C++ function signatures.

external references

The sphinx_immaterial.apidoc.cpp.external_cpp_references extension will allow for custom external references to other C++ related projects. For example, you can use this extension to cross-reference docs generated by Doxygen with a project that was documented with breathe.

[t-b]

Nice theme! Most links in your post give a 404 though.

[2bndy5]

Thanks. I've updated the links... We had a bit of a refactor with docs' and extensions' structure since I posted this, so thanks for letting me know about the broken links.

We also now have a very alpha ext that uses libclang to mimic autosummary on C++ srcs, but it isn't polished yet.