Cpp domain improvements #64

jbms · 2022-04-21T20:13:00Z

This adds a number of improvements for the C++ domain:

Improved styling
clang-format-based signature formatting
Support for resolving cpp domain references to external links, with specific support for cppreference.com
Support for #include directives in C++ signatures to indicate the required header
Support for cross-linking parameters in C and C++ domains
Support for "synopses" of C/C++ domain objects shown in tooltips and search results
Option for including object description fields in TOC

2bndy5

First glance

I'll dive into the src changes later. This is just what I noticed in the docs changes.

docs/external_cpp_references.rst

docs/conf.py

docs/external_cpp_references.rst

docs/format_signatures.rst

docs/index.rst

docs/conf.py

package.json

docs/cpp.rst

sphinx_immaterial/apidoc_formatting.py

sphinx_immaterial/cpp_domain_fixes.py

src/assets/stylesheets/main/_api.scss

sphinx_immaterial/format_signatures.py

docs/cpp.rst

docs/format_signatures.rst

docs/cppreference.rst

jbms · 2022-04-23T22:53:56Z

Thanks for your review @2bndy5 --- I believe I have now addressed all of your comments.

I also added some new functionality --- synopses of C/C++ domain objects displayed as tooltips and in search results.

This extension allows signatures to be formatted using clang-format.

jbms · 2022-04-24T02:23:34Z

Wow! The description fields feature is something I've dreamed of for years. And, you just dished it out like a side entree rofl . I'm reviewing those changes now - everything else looks good.

To be clear, include_object_description_fields_in_toc just controls whether "Parameters", "Returns", etc. end up in the TOC.

Whether the individual parameters themselves end up in the TOC is independent of that currently, and requires domain-specific support --- this PR adds support for that to the C++ domain (in the cross-link parameters commit). And in the tensorstore docs I also do that for Python and JSON, but those changes aren't part of this theme yet.

However, it looks a bit weird to have the individual parameters in the TOC without a "Parameters" heading.

2bndy5 · 2022-04-24T02:48:47Z

However, it looks a bit weird to have the individual parameters in the TOC without a "Parameters" heading.

I am seeing a section for Parameters and such
in the python domain

and in the C++ domain

docs/api.rst

docs/cpp.rst

2bndy5 · 2022-04-24T03:12:53Z

I've noticed that the tooltips for confval references no longer show up.

I wasn't aware that they had tooltips --- can you explain a bit more what you mean?

I must have been mis-remembering this. I thought that hovering over a confval ToC entry or inline xref would yield a tooltip like "option_name (confval)". But, I can't seem to find an example of this anywhere (not even in sphinx-doc.org). Please disregard.

2bndy5 · 2022-04-24T03:19:35Z

The param direction for C++ domain looks a bit sequestered.

Especially for wide viewports.

I couldn't devise a CSS way to replace the floatr: right property. My idea was either append to the end of a param name or use a nested dl in which the dt is the param direction and the dd is the param name(s).

… TOC

jbms · 2022-04-24T03:39:04Z

The param direction for C++ domain looks a bit sequestered. Especially for wide viewports.

I couldn't devise a CSS way to replace the floatr: right property. My idea was either append to the end of a param name or use a nested dl in which the dt is the param direction and the dd is the param name(s).

I am also not too satisfied with the appearance of this, but I couldn't figure out a better alternative. Perhaps could be revised in the future.

2bndy5

As always these changes go above and beyond my expectations! Thank you for this!

2bndy5 · 2022-04-24T05:32:04Z

I'm going to tag the master branch head, but I wanted to ask if you think this is a minor version bump or a patch bump. I've been using minor version bumps for merges from upstream, so I'm leaning toward a patch version bump.

jbms · 2022-04-24T05:44:58Z

In general patch -> bug fixes only, while minor -> backwards compatible feature addition. I think if we synchronized our version numbers with mkdocs-material then a patch bump could make sense, but so far we have not done that, and as we add more independent sphinx-related functionality to this theme (such as in this PR), the upstream changes from mkdocs-material may not necessarily be the most significant changes. So I think minor version bump would make sense as well here, and maybe we won't bother to use a patch bump.

2bndy5 · 2022-04-24T06:49:53Z

Well I pushed a v0.5.0 tag, and setuptools_scm interpreted it as 0.5.0.post1.dev0 which got treated as a pre-release on pypi. So, fresh installs will still be getting v0.4.1. Pushing a tag v0.5 (after v0.5.0 tag was pushed) wasn't uploaded to pypi (only test-pypi).

I'm guessing the post1.dev0 is indicative of pre-release status on pypi, but I don't know what I could've done to prevent that from being appended.

Previously, binary files like .gif were being incorrectly converted, leading to a dirty working tree and `post` version numbers selected by setuptools_scm. #64 (comment)

jbms · 2022-04-24T17:39:09Z

I have a fix for the version number issue. I removed the v0.5.0 tag and the post release from pypi --- we can push a new v0.5.0 tag once the PR is merged.

Previously, binary files like .gif were being incorrectly converted, leading to a dirty working tree and `post` version numbers selected by setuptools_scm. #64 (comment)

Small patches to #64 changes

Fix parallel build

f93287c

jbms requested a review from 2bndy5 April 21, 2022 20:13

jbms force-pushed the cpp-domain-improvements branch 3 times, most recently from 256266d to 5818d13 Compare April 21, 2022 21:01

2bndy5 requested changes Apr 22, 2022

View reviewed changes

2bndy5 linked an issue Apr 22, 2022 that may be closed by this pull request

multilined cpp function signatures split between param name and datatype #14

Closed