Add object description options mechanism

[jbms]

This replaces manny config options with a more general "object
description options" mechanism that allows various options to be
configured on a per domain/object type basis.

This commit also adds a number of features built on top of that mechanism:

• Generating object description synopses for the std domain, including
  custom object types added using app.add_object_type.

• Excluding certain object types from the TOC

• Excluding the object type from the cross-reference tooltip.

Fixes #70.

[2bndy5]

I just pushed the v0.5.0 tag without knowing your work on this was changing the config option names. These config option changes seem like a breaking change, so I'd use a major version bump for the next tag.

[jbms]

It is true that it is a breaking change, but on the other hand if we get this in soon I doubt too many people will have used the new options yet.

Also v0 generally means no stability guarantees.

But yeah it could make sense to increase to v1.

[2bndy5]

I'm ok with bumping minor version because I'd also consider v0 as "beta" state.

[2bndy5]

Please hold. I'm having trouble getting the solution to #70 working. I'm trying

object_description_pattern = [
    ("cpp:functionParam", dict(include_in_toc=False, generate_synopses=None))
]

But it still shows param in the toc and synopses are the entire paragraph (albeit still incorrect because of #69 )

[2bndy5]

Nevermind. I see the typo in the config option now. That also explains why the docs weren't rebuilding when I changed the typo'd option's setting.

All is good to go when you are.

[2bndy5]

According to the docs you added, the object_description_options_map is a dict and object_description_options_patterns is a list. But all example snippets that use a list are assigned to object_description_options_map.

I'm starting to notice that this more generic approach (making the user specify a specific object type) is too generic as it requires intimate knowledge of sphinx inner workings (most of which aren't really documented like functionParam). Add regex into the mix, and you've got a pretty confusing user interface.

[jbms]

I will have to fix the doc issues. It could be nice to have a more powerful version of rst-example that lets us use modified conf.py but that might be tricky to implement.

Most of the time the object type matches the directive name so it should be fairly easy to understand. However it is true that the param types are hidden --- we would need to document them.

[2bndy5]

Originally, I had two rst-results type directives. Only the simpler form made it to PR. The other more complicated form was meant to take the first literal block designated as RST (via the node's language property) and output that rendered. What I wanted was to be able to feed it tabbed content and show the result below the tabbed content (despite which tab was active). But, it was harder to implement (trying to compensate for user error) and buggy (absent a closing html div tag).

Wouldn't using a modified conf.py for an example snippet require a independent (or possible divergent from primary) sphinx env object? That sounds a bit more than just "tricky". It would be great for tests/validation though.

[2bndy5]

I could revisit the tabbed results idea and grab the first literal block with a caption title ending in "conf.py" (probably would use os.path for that). Then any code in the conf.py snippet would be temporarily augmented to the app.env.config (restoring the env would be the tricky part - interpreting string literals as python code would be the hard part). This is all subject to using code-block directive properly (via language and caption properties). I would still need to solve the missing </div> problem though (felt like I was going bald trying to resolve that).

[jbms]

Yeah, using a modified conf.py would require running a separate sphinx build entirely (but presumably just for a single page) and then somehow incorporating the result into the main documentation. Probably would work best as a link to a separate page, or embedded as an iframe that is zoomed out perhaps.

This would be particularly nice for demonstrating the mkdocs-material features options.

[2bndy5]

iframe idea might be more complicated since it uses a isolated DOM.

[2bndy5]

I also can't seem to get include_object_description_fields_in_toc=False to work.

object_description_options_patterns = [
    ("cpp:.*", dict(include_object_description_fields_in_toc=False)),
]

[2bndy5]

It seems that option is actually named include_fields_in_toc now. ("cpp:.*", dict(include_fields_in_toc=False)) works.

[jbms]

It seems that option is actually named include_fields_in_toc now. ("cpp:.*", dict(include_fields_in_toc=False)) works.

Fixed.

[2bndy5]

Testing looks good now. I can't find any other objections.

[jbms]

Thanks for the very thorough review!