Mkdocstrings

Previous

Documentation from code

Reference

Limits

This theme tries to support the output of the python handler first. We do not know how it behaves with other languages.

Installation

pip install 'mkdocstrings[python]'

uv add 'mkdocstrings[python]'

poetry add 'mkdocstrings[python]'

Configuration

# mkdocs.yml

plugins:
  - mkdocstrings

You can look at all the available options in the python handler documentation.

Important

If you do not define show_root_heading, the theme sets it to true by default.

Syntax

::: shadcn.plugins.excalidraw.ExcalidrawPlugin
    options:
        members: true
        heading_level: 3
        docstring_section_style: table

shadcn.plugins.excalidraw.ExcalidrawPlugin

Bases: RouterMixin, BasePlugin[ExcalidrawPluginConfig]

This plugin enabled the real time edition of excalidraw scenes in development mode

Source code in shadcn/plugins/excalidraw.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
class ExcalidrawPlugin(RouterMixin, BasePlugin[ExcalidrawPluginConfig]):
    """This plugin enabled the real time edition of
    excalidraw scenes in development mode"""

    is_dev_server = False
    """Internal flag to detect if we are in development mode."""

    def on_startup(self, *, command, dirty: bool):
        """Detect if the server is running in development mode."""
        self.is_dev_server = command == "serve"

    def on_config(self, config: MkDocsConfig, **kwargs):
        """Three operations are performed:

        - detect and create the excalidraw directory
        - load the internal excalidraw markdown extension
        - inject the HTTP routes needed to handle excalidraw scenes and SVGs
        """
        base = os.path.dirname(config["config_file_path"])
        excalidraw_path = os.path.join(base, self.config.directory)
        extension_config = {
            "base_dir": excalidraw_path,
            "svg_only": not self.is_dev_server,
        }
        log.debug(
            f"Loading markdown extension 'shadcn.extensions.excalidraw' "
            f"with configuration: {extension_config}"
        )
        config["markdown_extensions"].append("shadcn.extensions.excalidraw")
        config["mdx_configs"]["shadcn.extensions.excalidraw"] = (
            extension_config
        )
        # create directory
        log.debug(f"creating excalidraw directory: {excalidraw_path}")
        os.makedirs(excalidraw_path, exist_ok=True)

        # these routes are injected in on_serve
        log.debug("injecting HTTP routes for excalidraw plugin")
        self.add_route(
            "/excalidraw/scene",
            scene_handler_factory(excalidraw_path),
            method=["GET", "POST"],
        )
        self.add_route(
            "/excalidraw/svg",
            svg_handler_factory(excalidraw_path),
            method=["GET", "POST"],
        )

is_dev_server = False class-attribute instance-attribute

Internal flag to detect if we are in development mode.

on_config(config, **kwargs)

Three operations are performed:

  • detect and create the excalidraw directory
  • load the internal excalidraw markdown extension
  • inject the HTTP routes needed to handle excalidraw scenes and SVGs
Source code in shadcn/plugins/excalidraw.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def on_config(self, config: MkDocsConfig, **kwargs):
    """Three operations are performed:

    - detect and create the excalidraw directory
    - load the internal excalidraw markdown extension
    - inject the HTTP routes needed to handle excalidraw scenes and SVGs
    """
    base = os.path.dirname(config["config_file_path"])
    excalidraw_path = os.path.join(base, self.config.directory)
    extension_config = {
        "base_dir": excalidraw_path,
        "svg_only": not self.is_dev_server,
    }
    log.debug(
        f"Loading markdown extension 'shadcn.extensions.excalidraw' "
        f"with configuration: {extension_config}"
    )
    config["markdown_extensions"].append("shadcn.extensions.excalidraw")
    config["mdx_configs"]["shadcn.extensions.excalidraw"] = (
        extension_config
    )
    # create directory
    log.debug(f"creating excalidraw directory: {excalidraw_path}")
    os.makedirs(excalidraw_path, exist_ok=True)

    # these routes are injected in on_serve
    log.debug("injecting HTTP routes for excalidraw plugin")
    self.add_route(
        "/excalidraw/scene",
        scene_handler_factory(excalidraw_path),
        method=["GET", "POST"],
    )
    self.add_route(
        "/excalidraw/svg",
        svg_handler_factory(excalidraw_path),
        method=["GET", "POST"],
    )

on_startup(*, command, dirty)

Detect if the server is running in development mode.

Source code in shadcn/plugins/excalidraw.py 
93
94
95
def on_startup(self, *, command, dirty: bool):
    """Detect if the server is running in development mode."""
    self.is_dev_server = command == "serve"
Excalidraw