You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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).
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:
classClass:
__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:
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 🙂
The text was updated successfully, but these errors were encountered:
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).
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:
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: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 🙂
The text was updated successfully, but these errors were encountered: