feature: Fine-grain configuration

[pawamoy]

Is your feature request related to a problem? Please describe.

Sometimes users want to render a whole module, but customize the appearance of a few members lower in the object tree.
The current configuration system does not allow that. We only have global options, and local options, and the final options constructed from both are used for all children objects.

Describe the solution you'd like

Fine-grain configuration.

My latest idea to handle that is the following: in global and local options, support a new key to declare options by object identifier (handler-specific ids).

plugins:
- mkdocstrings:
    handlers:
      python:
        options_per_object:
          package.module.Class.method:
            show_source: false

::: package.module
    options_per_object:
      package.module.Class.method:
        show_source: false

Options for a specific object would affect only this object, and none of its members. Though maybe we could support a propagate option to propagate to children.

Rejected ideas

Configuration in code

Adding special variables in the code itself to bind configuration to objects directly:

class Class:
    __mkdocstrings_options__ = {...}

It is not uncommon to render the same object multiple times with different options. This solution wouldn't play well with that.

Loading configuration from external file

Listing configuration per object in a known external file such as mkdocstrings.python.yml for the Python handler:

package.module.Class:
  show_source: false
package.module.Class.method:
  show_docstring_description: false

But once again, it is not uncommon to render the same object multiple times with different options, so this solution wouldn't play well with that either. We could let users choose the configuration files, with paths in global/local option (config_file: relative/path/to/python_options.yml), but that adds an indirection which makes things harder to read, write and debug.

Describe alternatives you've considered

The only alternative is to manually (or automatically with scripts) build the tree of rendered objects, with lots of ::: lines, but that doesn't integrate as well (divs are not nested, disallowing indentation for example). This could be improved with a PyMDown Block extension though, which can nest itself.

Additional context

This has been brought up multiple times in Gitter at least.

I'd love to get feedback, use-cases and/or other suggestions and ideas from interested users 🙂