Integrate markdown-callouts extension

Enable it for doc comments content and add custom admonition styles

Author: oprypin

docs/extras.md

@@ -4,6 +4,63 @@
 
 For most [usages it is recommended](README.md#usage) to enable the "deduplicate-toc" Markdown extension, which comes bundled with *mkdocstrings-crystal*. It de-duplicates consecutive items that have the same title in the table of contents. This is important because Crystal can have multiple overloads of a method but in the ToC only their names are shown.
 
+## "callouts" extension
+
+*mkdocstrings-crystal* auto-enables the ["callouts" extension][] for Markdown (only within doc comments' content), so you can use that syntax instead of the common ["admonition" extension][]'s syntax.
+
+!!! example "example.cr"
+    ```crystal
+    # Frobs the bar
+    #
+    # DEPRECATED: Use `baz` instead.
+    def frob(bar)
+    end
+    ```
+
+You can also enable that extension for the whole site:
+
+!!! example "mkdocs.yml"
+    ```yaml
+    markdown_extensions:
+      - callouts
+    ```
+
+["callouts" extension]: https://github.com/oprypin/markdown-callouts/
+["admonition" extension]: https://python-markdown.github.io/extensions/admonition/
+
+### Admonition styles
+
+In addition to the [usual admonition styles](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types), *mkdocstrings-crystal* injects styling for the Material theme to enable the following admonition kinds, used [in Crystal documentation](https://crystal-lang.org/reference/syntax_and_semantics/documenting_code.html#admonitions):
+
+<style>
+--8<-- "mkdocstrings/templates/crystal/material/style.css"
+
+.admonition p>code {
+    display: inline-block;
+    width: 49%;
+}
+</style>
+
+!!! todo
+    `TODO: ` `!!! todo`
+
+!!! note
+    `NOTE: ` `!!! note`
+
+!!! bug
+    `BUG: ` `!!! bug`
+
+!!! fixme
+    `FIXME: ` `!!! fixme`
+
+!!! deprecated
+    `DEPRECATED: ` `!!! deprecated`
+
+!!! optimize
+    `OPTIMIZE: ` `!!! optimize`
+
+Both the default styles and the extra styles work with both the ["callouts" extension][] (write them in all-uppercase) and the ["admonition" extension][] (write them in all-lowercase).
+
 ## Support for [MkDocs "macros" plugin](https://github.com/fralau/mkdocs_macros_plugin)
 
 *Without* support, you have to access the doc root as

mkdocstrings/handlers/crystal/renderer.py

@@ -3,6 +3,7 @@
 from typing import Optional, TypeVar, Union
 
 import jinja2
+import markdown_callouts
 from markdown import Markdown  # type: ignore
 from markdown.extensions import Extension, fenced_code  # type: ignore
 from markdown.treeprocessors import Treeprocessor
@@ -54,6 +55,7 @@ def update_env(self, md: Markdown, config: dict) -> None:
         del md.inlinePatterns["html"]
 
         md.treeprocessors.register(_RefInsertingTreeprocessor(md), "mkdocstrings_crystal_xref", 12)
+        markdown_callouts.CalloutsExtension().extendMarkdown(md)
 
         self.env.trim_blocks = True
         self.env.lstrip_blocks = True

mkdocstrings/templates/crystal/material/style.css

@@ -12,3 +12,69 @@ a.doc-source-link::after {
   content: "]";
   color: var(--md-typeset-color);
 }
+
+/* Adaptation of https://crystal-lang.org/reference/syntax_and_semantics/documenting_code.html#admonitions to mkdocs-material */
+
+:root {
+    /* Icons from https://github.com/Templarian/MaterialDesign/tree/e42f3f41dd46bc033f11c0e5eed7fb742af6e74e/svg */
+    /* format-list-checkbox */
+    --md-admonition-icon--todo: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21,19V17H8V19H21M21,13V11H8V13H21M8,7H21V5H8V7M4,5V7H6V5H4M3,5A1,1 0 0,1 4,4H6A1,1 0 0,1 7,5V7A1,1 0 0,1 6,8H4A1,1 0 0,1 3,7V5M4,11V13H6V11H4M3,11A1,1 0 0,1 4,10H6A1,1 0 0,1 7,11V13A1,1 0 0,1 6,14H4A1,1 0 0,1 3,13V11M4,17V19H6V17H4M3,17A1,1 0 0,1 4,16H6A1,1 0 0,1 7,17V19A1,1 0 0,1 6,20H4A1,1 0 0,1 3,19V17Z" /></svg>');
+    /* close-octagon */
+    --md-admonition-icon--deprecated: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8.27,3L3,8.27V15.73L8.27,21H15.73L21,15.73V8.27L15.73,3M8.41,7L12,10.59L15.59,7L17,8.41L13.41,12L17,15.59L15.59,17L12,13.41L8.41,17L7,15.59L10.59,12L7,8.41" /></svg>');
+}
+
+/* Based on https://github.com/squidfunk/mkdocs-material/blob/b3c0163b3b6b6e4d2cb4d50fbd535018042c4970/src/assets/stylesheets/main/extensions/markdown/_admonition.scss */
+
+/* "TODO": custom icon */
+.md-typeset .todo>.admonition-title:before, .md-typeset .todo>summary:before {
+    -webkit-mask-image: var(--md-admonition-icon--todo);
+    mask-image: var(--md-admonition-icon--todo);
+}
+
+/* "FIXME": "bug" icon, "failure" color */
+.md-typeset .admonition.fixme, .md-typeset details.fixme {
+    border-color: #ff5252
+}
+.md-typeset .fixme>.admonition-title, .md-typeset .fixme>summary {
+    background-color: rgba(255, 82, 82, .1);
+    border-color: #ff5252
+}
+.md-typeset .fixme>.admonition-title:before, .md-typeset .fixme>summary:before {
+    background-color: #ff5252;
+    -webkit-mask-image: var(--md-admonition-icon--bug);
+    mask-image: var(--md-admonition-icon--bug);
+    mask-repeat: no-repeat;
+    mask-size: contain
+}
+
+/* "DEPRECATED": custom icon, "warning" color */
+.md-typeset .admonition.deprecated, .md-typeset details.deprecated {
+    border-color: #ff9100
+}
+.md-typeset .deprecated>.admonition-title, .md-typeset .deprecated>summary {
+    background-color: rgba(255, 145, 0, .1);
+    border-color: #ff9100
+}
+.md-typeset .deprecated>.admonition-title:before, .md-typeset .deprecated>summary:before {
+    background-color: #ff9100;
+    -webkit-mask-image: var(--md-admonition-icon--deprecated);
+    mask-image: var(--md-admonition-icon--deprecated);
+    mask-repeat: no-repeat;
+    mask-size: contain
+}
+
+/* "OPTIMIZE": "danger" icon, "question" color */
+.md-typeset .admonition.optimize, .md-typeset details.optimize {
+    border-color: #64dd17
+}
+.md-typeset .optimize>.admonition-title, .md-typeset .optimize>summary {
+    background-color: rgba(100, 221, 23, .1);
+    border-color: #64dd17
+}
+.md-typeset .optimize>.admonition-title:before, .md-typeset .optimize>summary:before {
+    background-color: #64dd17;
+    -webkit-mask-image: var(--md-admonition-icon--danger);
+    mask-image: var(--md-admonition-icon--danger);
+    mask-repeat: no-repeat;
+    mask-size: contain
+}

pyproject.toml

@@ -17,6 +17,7 @@ deduplicate-toc = "mkdocstrings.handlers.crystal.deduplicate_toc:DeduplicateTocE
 [tool.poetry.dependencies]
 python = "^3.7"
 mkdocstrings = "^0.15.0"
+markdown-callouts = "^0.1.0"
 markupsafe = "^1.1.1"
 cached-property = "^1.5.2"
 Jinja2 = "^2.11.2"