Feature Request: Configurable Admonitions Mapping in mkdocs.yaml for mkdocstrings

[nh916]

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:

mkdocstrings:
  handlers:
    python:
      rendering:
        admonition_mappings:
          "Notes:": "note"
          "See Also:": "info"
          "Warning:": "warning"

• Sections beginning with Notes: could automatically transform into note admonitions.
• Sections beginning with See Also: could become info admonitions.
• Sections beginning with Warning: would be rendered as warning 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!

[pawamoy]

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 see-also:

/* 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:

See also:
    It works!

...gets rendered as:

The notes kind being unknown, it will default to note, so nothing to be done here.
Also admonitions whose title are Warning: will have the warning kind, so nothing to be done here either.

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 :)
"""