-
-
Notifications
You must be signed in to change notification settings - Fork 102
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Feature Request: Configurable Admonitions Mapping in mkdocs.yaml
for mkdocstrings
#664
Comments
Hey @nh916, thanks for the kind words and for the feature request ❤️! Do you by chance use the Material for MkDocs theme 🙂? What I would recommend instead of casting down the various admonitions parsed by Griffe into a subset of generally supported admonitions, is to augment the set of supported admonitions by creating custom ones: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions. Example for "See also" admonitions, for which the admonition kind becomes /* Custom admonition: see-also */
:root {
--md-admonition-icon--see-also: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.5 12a3.5 3.5 0 1 1-7 0 3.5 3.5 0 0 1 7 0Z"/><path d="M12 3.5c3.432 0 6.124 1.534 8.054 3.241 1.926 1.703 3.132 3.61 3.616 4.46a1.6 1.6 0 0 1 0 1.598c-.484.85-1.69 2.757-3.616 4.461-1.929 1.706-4.622 3.24-8.054 3.24-3.432 0-6.124-1.534-8.054-3.24C2.02 15.558.814 13.65.33 12.8a1.6 1.6 0 0 1 0-1.598c.484-.85 1.69-2.757 3.616-4.462C5.875 5.034 8.568 3.5 12 3.5ZM1.633 11.945a.115.115 0 0 0-.017.055c.001.02.006.039.017.056.441.774 1.551 2.527 3.307 4.08C6.691 17.685 9.045 19 12 19c2.955 0 5.31-1.315 7.06-2.864 1.756-1.553 2.866-3.306 3.307-4.08a.111.111 0 0 0 .017-.056.111.111 0 0 0-.017-.056c-.441-.773-1.551-2.527-3.307-4.08C17.309 6.315 14.955 5 12 5 9.045 5 6.69 6.314 4.94 7.865c-1.756 1.552-2.866 3.306-3.307 4.08Z"/></svg>');
}
.md-typeset .admonition.see-also,
.md-typeset details.see-also {
border-color: rgb(220, 139, 240);
}
.md-typeset .see-also>.admonition-title,
.md-typeset .see-also>summary {
background-color: rgba(142, 43, 155, 0.1);
}
.md-typeset .see-also>.admonition-title::before,
.md-typeset .see-also>summary::before {
background-color: rgb(220, 139, 240);
-webkit-mask-image: var(--md-admonition-icon--see-also);
mask-image: var(--md-admonition-icon--see-also);
} With this, the following admonition:
...gets rendered as: The Also also, note that in any case (with or without the Material theme, with or without custom admonitions) you can specify the kind and title in the docstring markup itself: """
See also: Custom title for my see-also admonition
It works!
Warning: Attention
A warning admonition but with title "Attention"
Info: See also
See also with the info style :)
""" |
Hello
mkdocstrings
maintainers and the wider community,First and foremost, a big thank you for developing
mkdocstrings
. It's been instrumental in producing stunning documentation for our projects!I'd like to discuss a potential feature that could enhance how docstrings are rendered, specifically regarding the automatic creation of admonitions.
Feature Enhancement
The current mechanism of generating admonitions from docstrings automatically is quite innovative, yet it doesn't provide granular control over how distinct docstring sections are rendered in the final output.
I propose an enhancement to allow mapping specific docstring sections to defined admonitions directly within the
mkdocs.yaml
. This could be realized with configuration options like the following:Notes:
could automatically transform intonote
admonitions.See Also:
could becomeinfo
admonitions.Warning:
would be rendered aswarning
admonitions.This added layer of customization would grant developers enhanced control over their documentation's presentation and prove exceedingly beneficial for extensive projects with consistent formatting needs.
Thank you for taking the time to consider this feature enhancement!
The text was updated successfully, but these errors were encountered: