Description
Is your feature request related to a problem? Please describe.
I am currently writing documentation for a project which will be consumed by both technical and non-technical users. As such I am always frustrated by not having control of what the title and toc entry label of my autodocumentated object will be.
Here's an example:
:: path.to.specific.module.class.or.function
options:
any_specific_mkdocstrings_options_for_this_identifier
The above will render a beautiful API documentation for my module/class/function with the desired settings and I love it! The only issue is that the heading will be the name of that particular object and toc label will be the same. So if I was documenting a function with the following path:
:: my_package.my_module.my_technical_function_name
The heading will be my_technical_function_name and the same will apply for the toc label. This is not very user-friendly for users who are non-technical and also makes it so that if I am intertwining the API documentation between markdown sections I have written, that the ToC is mixed between nice heading names with sentence case vs lower case technical function names.
The following example ToC depicts what I mean.
On This Page:
- Introduction
- Theoretical Background
- Functional Implementation
- my_technical_function_name
- Conclusion
And here is the example Page
# Introduction
blah blah blah
# Theoretical Background
blah blah blah
# Functional Implementation
# my_technical_function_name
# Conclusion
blah blah blah
Not very nice to look at it :').
Describe the solution you'd like
Adding the ability to define a custom name for an identifier to use as the toc label and header. Something like the example code below:
:: path.to.specific.module.class.or.function "My Pretty Object Name"
options:
any_specific_mkdocstrings_functions_for_this_identifier
This would render exactly as it does today except a header would be added above the function signature with "My Pretty Object Name" and that header would serve as the anchor for cross-references and use in the ToC
Applied to my example above, it would look like this:
# Introduction
blah blah blah
# Theoretical Background
blah blah blah
# :: my_package.my_module.my_technical_function_name "Functional Implementation"
# Conclusion
blah blah blah
The ToC would look like this:
On This Page:
- Introduction
- Theoretical Background
- Functional Implementation
- Conclusion
And the rendered page like this:
# Introduction
blah blah blah
# Theoretical Background
blah blah blah
# Functional Implementation
Beautiful API documentation for my_technical_function_name
# Conclusion
blah blah blah