search.json

{"config":{"separator":"[\\s\\-_,:!=\\[\\]()\\\\\"`/]+|\\.(?!\\d)"},"items":[{"location":"","level":1,"title":"mkdocstrings","text":"<p>Automatic documentation from sources, for MkDocs. Come have a chat or ask questions on our Gitter channel.</p> <p>Features - Installation - Quick usage</p> <p></p>","path":["Home","Overview"],"tags":[]},{"location":"#features","level":2,"title":"Features","text":"<ul> <li> <p>Language-agnostic:   just like MkDocs, mkdocstrings is written in Python but is language-agnostic.   It means you can use it with any programming language, as long as there is a   handler for it.   We currently have handlers for the   C,   Crystal,   GitHub Actions,   Python,   MATLAB,   TypeScript, and   VBA languages,   as well as for shell scripts/libraries.   Maybe you'd like to add another one to the list? </p> </li> <li> <p>Multiple themes support:   each handler can offer multiple themes. Currently, we offer the    Material theme    as well as basic support for the ReadTheDocs and MkDocs themes for the Python handler.</p> </li> <li> <p>Cross-references across pages: mkdocstrings makes it possible to reference headings in other Markdown files with the classic Markdown linking   syntax: <code>[identifier][]</code> or <code>[title][identifier]</code> -- and you don't need to remember which exact page this object was   on. This works for any heading that's produced by a mkdocstrings language handler, and you can opt to include   any Markdown heading into the global referencing scheme.</p> <p>Note: in versions prior to 0.15 all Markdown headers were included, but now you need to opt in.</p> </li> <li> <p>Cross-references across sites:   similarly to Sphinx's intersphinx extension,   mkdocstrings can reference API items from other libraries, given they provide an inventory and you load   that inventory in your MkDocs configuration.</p> </li> <li> <p>Inline injection in Markdown:   instead of generating Markdown files, mkdocstrings allows you to inject   documentation anywhere in your Markdown contents. The syntax is simple: <code>identifier</code> followed by a 4-spaces   indented YAML block. The identifier and YAML configuration will be passed to the appropriate handler   to collect and render documentation.</p> </li> <li> <p>Global and local configuration:   each handler can be configured globally in <code>mkdocs.yml</code>, and locally for each   \"autodoc\" instruction.</p> </li> <li> <p>Reasonable defaults:   you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.</p> </li> </ul>","path":["Home","Overview"],"tags":[]},{"location":"#used-by","level":2,"title":"Used by","text":"<p>mkdocstrings is used by well-known companies, projects and scientific teams: Ansible, Apache, FastAPI, Google, IBM, Jitsi, Microsoft, NVIDIA, Prefect, Pydantic, Textual, and more...</p>","path":["Home","Overview"],"tags":[]},{"location":"#installation","level":2,"title":"Installation","text":"<p>The <code>mkdocstrings</code> package doesn't provide support for any language: it's just a common base for language handlers. It means you likely want to install it with one or more official handlers, using extras. For example, to install it with Python support:</p> <pre><code>pip install 'mkdocstrings[python]'\n</code></pre> <p>Alternatively, you can directly install the language handlers themselves, which depend on <code>mkdocstrings</code> anyway:</p> <pre><code>pip install mkdocstrings-python\n</code></pre> <p>This will give you more control over the accepted range of versions for the handlers themselves.</p> <p>See the official language handlers.</p> <p>With <code>conda</code>:</p> <pre><code>conda install -c conda-forge mkdocstrings mkdocstrings-python\n</code></pre>","path":["Home","Overview"],"tags":[]},{"location":"#quick-usage","level":2,"title":"Quick usage","text":"<p>In <code>mkdocs.yml</code>:</p> <pre><code>site_name: \"My Library\"\n\ntheme:\n  name: \"material\"\n\nplugins:\n- search\n- mkdocstrings\n</code></pre> <p>In one of your markdown files:</p> <pre><code># Reference\n\n::: my_library.my_module.my_class\n</code></pre> <p>See the Usage section of the docs for more examples!</p>","path":["Home","Overview"],"tags":[]},{"location":"#sponsors","level":2,"title":"Sponsors","text":"Silver sponsors Bronze sponsors <p>And 7 more private sponsor(s).</p>","path":["Home","Overview"],"tags":[]},{"location":"changelog/","level":1,"title":"Changelog","text":"<p>All notable changes to this project will be documented in this file.</p> <p>The format is based on Keep a Changelog and this project adheres to Semantic Versioning.</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#103-2026-02-07","level":2,"title":"1.0.3 - 2026-02-07","text":"<p>Compare with 1.0.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes","level":3,"title":"Bug Fixes","text":"<ul> <li>Forward extension instances directly passed from Zensical (65b27ec by Timothée Mazzucotelli).</li> <li>Propagate Zensical's <code>zrelpath</code> processor (dbf263d by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#102-2026-01-24","level":2,"title":"1.0.2 - 2026-01-24","text":"<p>Compare with 1.0.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring","level":3,"title":"Code Refactoring","text":"<ul> <li>Use global instances for handlers and autorefs (9f79141 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#101-2026-01-19","level":2,"title":"1.0.1 - 2026-01-19","text":"<p>Compare with 1.0.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_1","level":3,"title":"Code Refactoring","text":"<ul> <li>Support manual cross-references in Zensical too (d37d907 by Timothée Mazzucotelli).</li> <li>Support cross-references in Zensical (f43f1ee by Timothée Mazzucotelli). PR-812</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#100-2025-11-27","level":2,"title":"1.0.0 - 2025-11-27","text":"<p>Compare with 0.30.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#breaking-changes","level":3,"title":"Breaking Changes","text":"<ul> <li><code>BaseHandler.name</code>: Attribute value was changed: <code>''</code> -&gt; unset</li> <li><code>BaseHandler.domain</code>: Attribute value was changed: <code>''</code> -&gt; unset</li> <li><code>BaseHandler.fallback_config</code>: Public object was removed</li> <li><code>BaseHandler.__init__(args)</code>: Parameter was removed</li> <li><code>BaseHandler.__init__(kwargs)</code>: Parameter was removed</li> <li><code>BaseHandler.__init__(theme)</code>: Parameter was added as required</li> <li><code>BaseHandler.__init__(custom_templates)</code>: Parameter was added as required</li> <li><code>BaseHandler.__init__(mdx)</code>: Parameter was added as required</li> <li><code>BaseHandler.__init__(mdx_config)</code>: Parameter was added as required</li> <li><code>BaseHandler.update_env(args)</code>: Parameter was removed</li> <li><code>BaseHandler.update_env(kwargs)</code>: Parameter was removed</li> <li><code>BaseHandler.update_env(config)</code>: Parameter was added as required</li> <li><code>Handlers.get_anchors</code>: Public object was removed (import from <code>mkdocstrings</code> directly)</li> <li><code>mkdocstrings.plugin</code>: Public module was removed (import from <code>mkdocstrings</code> directly)</li> <li><code>mkdocstrings.loggers</code>: Public module was removed (import from <code>mkdocstrings</code> directly)</li> <li><code>mkdocstrings.inventory</code>: Public module was removed (import from <code>mkdocstrings</code> directly)</li> <li><code>mkdocstrings.extension</code>: Public module was removed (import from <code>mkdocstrings</code> directly)</li> <li><code>mkdocstrings.handlers</code>: Public module was removed (import from <code>mkdocstrings</code> directly)</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_2","level":3,"title":"Code Refactoring","text":"<ul> <li>Remove deprecated code before v1 (de34044 by Timothée Mazzucotelli).</li> <li>Expect Zensical to pass extension configuration instead of loading it again from YAML (6b73d5a by Timothée Mazzucotelli).</li> <li>Expose the Markdown extension, to make mkdocstrings compatible with Zensical (6de2667 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0301-2025-09-19","level":2,"title":"0.30.1 - 2025-09-19","text":"<p>Compare with 0.30.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_1","level":3,"title":"Bug Fixes","text":"<ul> <li>Create default SSL context in main thread before downloading inventories (eec7fb4 by Çağlar Kutlu). Issue-796, PR-797</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0300-2025-07-23","level":2,"title":"0.30.0 - 2025-07-23","text":"<p>Compare with 0.29.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features","level":3,"title":"Features","text":"<ul> <li>Add <code>data-skip-inventory</code> boolean attribute for elements to skip registration in local inventory (f856160 by Bartosz Sławecki). Issue-671, PR-774</li> <li>Add I18N support (translations) (2b4ed54 by Nyuan Zhang). PR-645, Co-authored-by: Timothée Mazzucotelli dev@pawamoy.fr</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0291-2025-03-31","level":2,"title":"0.29.1 - 2025-03-31","text":"<p>Compare with 0.29.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#dependencies","level":3,"title":"Dependencies","text":"<ul> <li>Remove unused typing-extensions dependency (ba98661 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_2","level":3,"title":"Bug Fixes","text":"<ul> <li>Ignore invalid inventory lines (81caff5 by Josh Mitchell). PR-748</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_3","level":3,"title":"Code Refactoring","text":"<ul> <li>Rename loggers to \"mkdocstrings\" (1a98040 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0290-2025-03-10","level":2,"title":"0.29.0 - 2025-03-10","text":"<p>Compare with 0.28.3</p> <p>This is the last version before v1!</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#build","level":3,"title":"Build","text":"<ul> <li>Depend on MkDocs 1.6 (11bc400 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_1","level":3,"title":"Features","text":"<ul> <li>Support rendering backlinks through handlers (d4c7b9c by Timothée Mazzucotelli). Issue-723, Issue-mkdocstrings-python-153, PR-739</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_4","level":3,"title":"Code Refactoring","text":"<ul> <li>Save and forward titles to autorefs (f49fb29 by Timothée Mazzucotelli).</li> <li>Use a combined event (each split with a different priority) for <code>on_env</code> (8d1dd75 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0283-2025-03-08","level":2,"title":"0.28.3 - 2025-03-08","text":"<p>Compare with 0.28.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#deprecations","level":3,"title":"Deprecations","text":"<p>All public objects must now be imported from the top-level <code>mkdocstrings</code> module. Importing from submodules is deprecated, and will raise errors starting with v1. This should be the last deprecation before v1.</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#build_1","level":3,"title":"Build","text":"<ul> <li>Make <code>python</code> extra depend on latest mkdocstrings-python (1.16.2) (ba9003e by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_5","level":3,"title":"Code Refactoring","text":"<ul> <li>Finish exposing/hiding public/internal objects (0723fc2 by Timothée Mazzucotelli).</li> <li>Re-expose public API in the top-level <code>mkdocstrings</code> module (e66e080 by Timothée Mazzucotelli).</li> <li>Move modules to internal folder (23fe23f by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0282-2025-02-24","level":2,"title":"0.28.2 - 2025-02-24","text":"<p>Compare with 0.28.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#build_2","level":3,"title":"Build","text":"<ul> <li>Depend on mkdocs-autorefs &gt;= 1.4 (2c22bdc by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0281-2025-02-14","level":2,"title":"0.28.1 - 2025-02-14","text":"<p>Compare with 0.28.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_3","level":3,"title":"Bug Fixes","text":"<ul> <li>Renew MkDocs' <code>relpath</code> processor instead of using same instance (4ab180d by Timothée Mazzucotelli). Issue-mkdocs-3919</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0280-2025-02-03","level":2,"title":"0.28.0 - 2025-02-03","text":"<p>Compare with 0.27.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#breaking-changes_1","level":3,"title":"Breaking Changes","text":"<p>Although the following changes are \"breaking\" in terms of public API, we didn't find any public use of these classes and methods on GitHub.</p> <ul> <li><code>mkdocstrings.extension.AutoDocProcessor.__init__(parser)</code>: Parameter was removed</li> <li><code>mkdocstrings.extension.AutoDocProcessor.__init__(md)</code>: Positional parameter was moved</li> <li><code>mkdocstrings.extension.AutoDocProcessor.__init__(config)</code>: Parameter was removed</li> <li><code>mkdocstrings.extension.AutoDocProcessor.__init__(handlers)</code>: Parameter kind was changed: <code>positional or keyword</code> -&gt; <code>keyword-only</code></li> <li><code>mkdocstrings.extension.AutoDocProcessor.__init__(autorefs)</code>: Parameter kind was changed: <code>positional or keyword</code> -&gt; <code>keyword-only</code></li> <li><code>mkdocstrings.extension.MkdocstringsExtension.__init__(config)</code>: Parameter was removed</li> <li><code>mkdocstrings.extension.MkdocstringsExtension.__init__(handlers)</code>: Positional parameter was moved</li> <li><code>mkdocstrings.extension.MkdocstringsExtension.__init__(autorefs)</code>: Positional parameter was moved</li> <li><code>mkdocstrings.handlers.base.Handlers.__init__(config)</code>: Parameter was removed</li> <li><code>mkdocstrings.handlers.base.Handlers.__init__(theme)</code>: Parameter was added as required</li> <li><code>mkdocstrings.handlers.base.Handlers.__init__(default)</code>: Parameter was added as required</li> <li><code>mkdocstrings.handlers.base.Handlers.__init__(inventory_project)</code>: Parameter was added as required</li> <li><code>mkdocstrings.handlers.base.Handlers.__init__(tool_config)</code>: Parameter was added as required</li> </ul> <p>Similarly, the following parameters were renamed, but the methods are only called from our own code, using positional arguments.</p> <ul> <li><code>mkdocstrings.handlers.base.BaseHandler.collect(config)</code>: Parameter was renamed <code>options</code></li> <li><code>mkdocstrings.handlers.base.BaseHandler.render(config)</code>: Parameter was renamed <code>options</code></li> </ul> <p>Finally, the following method was removed, but this is again taken into account in our own code:</p> <ul> <li><code>mkdocstrings.handlers.base.BaseHandler.get_anchors</code>: Public object was removed</li> </ul> <p>For these reasons, and because we're still in v0, we do not bump to v1 yet. See following deprecations.</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#deprecations_1","level":3,"title":"Deprecations","text":"<p>mkdocstrings 0.28 will start emitting these deprecations warnings:</p> <p>The <code>handler</code> argument is deprecated. The handler name must be specified as a class attribute.</p> <p>Previously, the <code>get_handler</code> function would pass a <code>handler</code> (name) argument to the handler constructor. This name must now be set on the handler's class directly.</p> <pre><code>class MyHandler:\n    name = \"myhandler\"\n</code></pre> <p>The <code>domain</code> attribute must be specified as a class attribute.</p> <p>The <code>domain</code> class attribute on handlers is now mandatory and cannot be an empty string.</p> <pre><code>class MyHandler:\n    domain = \"mh\"\n</code></pre> <p>The <code>theme</code> argument must be passed as a keyword argument.</p> <p>This argument could previously be passed as a positional argument (from the <code>get_handler</code> function), and must now be passed as a keyword argument.</p> <p>The <code>custom_templates</code> argument must be passed as a keyword argument.</p> <p>Same as for <code>theme</code>, but with <code>custom_templates</code>.</p> <p>The <code>mdx</code> argument must be provided (as a keyword argument).</p> <p>The <code>get_handler</code> function now receives a <code>mdx</code> argument, which it must forward to the handler constructor and then to the base handler, either explicitly or through <code>**kwargs</code>:</p> ExplicitlyThrough <code>**kwargs</code> <pre><code>def get_handler(..., mdx, ...):\n    return MyHandler(..., mdx=mdx, ...)\n\n\nclass MyHandler:\n    def __init__(self, ..., mdx, ...):\n        super().__init__(..., mdx=mdx, ...)\n</code></pre> <pre><code>def get_handler(..., **kwargs):\n    return MyHandler(..., **kwargs)\n\n\nclass MyHandler:\n    def __init__(self, ..., **kwargs):\n        super().__init__(**kwargs)\n</code></pre> <p>In the meantime we still retrieve this <code>mdx</code> value at a different moment, by reading it from the MkDocs configuration.</p> <p>The <code>mdx_config</code> argument must be provided (as a keyword argument).</p> <p>Same as for <code>mdx</code>, but with <code>mdx_config</code>.</p> <p>mkdocstrings v1 will stop handling 'import' in handlers configuration. Instead your handler must define a <code>get_inventory_urls</code> method that returns a list of URLs to download.</p> <p>Previously, mkdocstrings would pop the <code>import</code> key from a handler's configuration to download each item (URLs). Items could be strings, or dictionaries with a <code>url</code> key. Now mkdocstrings gives back control to handlers, which must store this inventory configuration within them, and expose it again through a <code>get_inventory_urls</code> method. This method returns a list of tuples: an URL, and a dictionary of options that will be passed again to their <code>load_inventory</code> method. Handlers have now full control over the \"inventory\" setting.</p> <pre><code>from copy import deepcopy\n\n\ndef get_handler(..., handler_config, ...):\n    return MyHandler(..., config=handler_config, ...)\n\n\nclass MyHandler:\n    def __init__(self, ..., config, ...):\n        self.config = config\n\n    def get_inventory_urls(self):\n        config = deepcopy(self.config[\"import\"])\n        return [(inv, {}) if isinstance(inv, str) else (inv.pop(\"url\"), inv) for inv in config]\n</code></pre> <p>Changing the name of the key (for example from <code>import</code> to <code>inventories</code>) involves a change in user configuration, and both keys will have to be supported by your handler for some time.</p> <pre><code>def get_handler(..., handler_config, ...):\n    if \"inventories\" not in handler_config and \"import\" in handler_config:\n        warn(\"The 'import' key is renamed 'inventories'\", FutureWarning)\n        handler_config[\"inventories\"] = handler_config.pop(\"import\")\n    return MyHandler(..., config=handler_config, ...)\n</code></pre> <p>Setting a fallback anchor function is deprecated and will be removed in a future release.</p> <p>This comes from mkdocstrings and mkdocs-autorefs, and will disappear with mkdocstrings v0.28.</p> <p>mkdocstrings v1 will start using your handler's <code>get_options</code> method to build options instead of merging the global and local options (dictionaries).</p> <p>Handlers must now store their own global options (in an instance attribute), and implement a <code>get_options</code> method that receives <code>local_options</code> (a dict) and returns combined options (dict or custom object). These combined options are then passed to <code>collect</code> and <code>render</code>, so that these methods can use them right away.</p> <pre><code>def get_handler(..., handler_config, ...):\n    return MyHandler(..., config=handler_config, ...)\n\n\nclass MyHandler:\n    def __init__(self, ..., config, ...):\n        self.config = config\n\n    def get_options(local_options):\n        return {**self.default_options, **self.config[\"options\"], **local_options}\n</code></pre> <p>The <code>update_env(md)</code> parameter is deprecated. Use <code>self.md</code> instead.</p> <p>Handlers can remove the <code>md</code> parameter from their <code>update_env</code> method implementation, and use <code>self.md</code> instead, if they need it.</p> <p>No need to call <code>super().update_env()</code> anymore.</p> <p>Handlers don't have to call the parent <code>update_env</code> method from their own implementation anymore, and can just drop the call.</p> <p>The <code>get_anchors</code> method is deprecated. Declare a <code>get_aliases</code> method instead, accepting a string (identifier) instead of a collected object.</p> <p>Previously, handlers would implement a <code>get_anchors</code> method that received a data object (typed <code>CollectorItem</code>) to return aliases for this object. This forced mkdocstrings to collect this object through the handler's <code>collect</code> method, which then required some logic with \"fallback config\" as to prevent unwanted collection. mkdocstrings gives back control to handlers and now calls <code>get_aliases</code> instead, which accepts an <code>identifier</code> (string) and lets the handler decide how to return aliases for this identifier. For example, it can replicate previous behavior by calling its own <code>collect</code> method with its own \"fallback config\", or do something different (cache lookup, etc.).</p> <pre><code>class MyHandler:\n    def get_aliases(identifier):\n        try:\n            obj = self.collect(identifier, self.fallback_config)\n            # or obj = self._objects_cache[identifier]\n        except CollectionError:  # or KeyError\n            return ()\n        return ...  # previous logic in `get_anchors`\n</code></pre> <p>The <code>config_file_path</code> argument in <code>get_handler</code> functions is deprecated. Use <code>tool_config.get('config_file_path')</code> instead.</p> <p>The <code>config_file_path</code> argument is now deprecated and only passed to <code>get_handler</code> functions if they accept it. If you used it to compute a \"base directory\", you can now use the <code>tool_config</code> argument instead, which is the configuration of the SSG tool in use (here MkDocs):</p> <pre><code>base_dir = Path(tool_config.config_file_path or \"./mkdocs.yml\").parent\n</code></pre> <p>Most of these warnings will disappear with the next version of mkdocstrings-python.</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_4","level":3,"title":"Bug Fixes","text":"<ul> <li>Update handlers in JSON schema to be an object instead of an array (3cf7d51 by Matthew Messinger). Issue-733, PR-734</li> <li>Fix broken table of contents when nesting autodoc instructions (12c8f82 by Timothée Mazzucotelli). Issue-348</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_6","level":3,"title":"Code Refactoring","text":"<ul> <li>Pass <code>config_file_path</code> to <code>get_handler</code> if it expects it (8c476ee by Timothée Mazzucotelli).</li> <li>Give back inventory control to handlers (b84653f by Timothée Mazzucotelli). Related-to-issue-719</li> <li>Give back control to handlers on how they want to handle global/local options (c00de7a by Timothée Mazzucotelli). Issue-719</li> <li>Deprecate base handler's <code>get_anchors</code> method in favor of <code>get_aliases</code> method (7a668f0 by Timothée Mazzucotelli).</li> <li>Register all identifiers of rendered objects into autorefs (434d8c7 by Timothée Mazzucotelli).</li> <li>Use mkdocs-get-deps' download utility to remove duplicated code (bb87cd8 by Timothée Mazzucotelli).</li> <li>Clean up data passed down from plugin to extension and handlers (b8e8703 by Timothée Mazzucotelli). PR-726</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0270-2024-11-08","level":2,"title":"0.27.0 - 2024-11-08","text":"<p>Compare with 0.26.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_2","level":3,"title":"Features","text":"<ul> <li>Add support for authentication in inventory file URLs (1c23c1b by Stefan Mejlgaard). Issue-707, PR-710</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#performance-improvements","level":3,"title":"Performance Improvements","text":"<ul> <li>Reduce footprint of template debug messages (5648e5a by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_7","level":3,"title":"Code Refactoring","text":"<ul> <li>Use %-formatting for logging messages (0bbb8ca by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0262-2024-10-12","level":2,"title":"0.26.2 - 2024-10-12","text":"<p>Compare with 0.26.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#build_3","level":3,"title":"Build","text":"<ul> <li>Drop support for Python 3.8 (f26edeb by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0261-2024-09-06","level":2,"title":"0.26.1 - 2024-09-06","text":"<p>Compare with 0.26.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_5","level":3,"title":"Bug Fixes","text":"<ul> <li>Instantiate config of the autorefs plugin when it is not enabled by the user (db2ab34 by Timothée Mazzucotelli). Issue-autorefs#57</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0260-2024-09-02","level":2,"title":"0.26.0 - 2024-09-02","text":"<p>Compare with 0.25.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#build_4","level":3,"title":"Build","text":"<ul> <li>Upgrade Python-Markdown lower bound to 3.6 (28565f9 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#dependencies_1","level":3,"title":"Dependencies","text":"<ul> <li>Depend on mkdocs-autorefs v1 (33aa573 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_3","level":3,"title":"Features","text":"<ul> <li>Allow hooking into autorefs when converting Markdown docstrings (b63e726 by Timothée Mazzucotelli). Based-on-PR-autorefs#46</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0252-2024-07-25","level":2,"title":"0.25.2 - 2024-07-25","text":"<p>Compare with 0.25.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_8","level":3,"title":"Code Refactoring","text":"<ul> <li>Give precedence to Markdown heading level (<code>##</code>) (2e5f89e by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0251-2024-05-05","level":2,"title":"0.25.1 - 2024-05-05","text":"<p>Compare with 0.25.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_6","level":3,"title":"Bug Fixes","text":"<ul> <li>Always descend into sub-headings when re-applying their label (cb86e08 by Timothée Mazzucotelli). Issue-mkdocstrings/python-158</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0250-2024-04-27","level":2,"title":"0.25.0 - 2024-04-27","text":"<p>Compare with 0.24.3</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_4","level":3,"title":"Features","text":"<ul> <li>Support <code>once</code> parameter in logging methods, allowing to log a message only once with a given logger (1532b59 by Timothée Mazzucotelli).</li> <li>Support blank line between <code>path</code> and YAML options (d799d2f by Timothée Mazzucotelli). Issue-450</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_9","level":3,"title":"Code Refactoring","text":"<ul> <li>Allow specifying name of template loggers (c5b5f69 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0243-2024-04-05","level":2,"title":"0.24.3 - 2024-04-05","text":"<p>Compare with 0.24.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_7","level":3,"title":"Bug Fixes","text":"<ul> <li>Support HTML toc labels with Python-Markdown 3.6+ (uncomment code...) (7fe3e5f by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0242-2024-04-02","level":2,"title":"0.24.2 - 2024-04-02","text":"<p>Compare with 0.24.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_8","level":3,"title":"Bug Fixes","text":"<ul> <li>Support HTML toc labels with Python-Markdown 3.6+ (c0d0090 by Timothée Mazzucotelli). Issue-mkdocstrings/python-143</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0241-2024-02-27","level":2,"title":"0.24.1 - 2024-02-27","text":"<p>Compare with 0.24.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_10","level":3,"title":"Code Refactoring","text":"<ul> <li>Support new pymdownx-highlight options (a7a2907 by Timothée Mazzucotelli).</li> <li>Backup anchors with id and no href, for compatibility with autorefs' Markdown anchors (b5236b4 by Timothée Mazzucotelli). PR-#651, Related-to-mkdocs-autorefs#39, Co-authored-by: Oleh Prypin oleh@pryp.in</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0240-2023-11-14","level":2,"title":"0.24.0 - 2023-11-14","text":"<p>Compare with 0.23.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_5","level":3,"title":"Features","text":"<ul> <li>Cache downloaded inventories as local file (ce84dd5 by Oleh Prypin). PR #632</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_9","level":3,"title":"Bug Fixes","text":"<ul> <li>Make <code>custom_templates</code> relative to the config file (370a61d by Waylan Limberg). Issue #477, PR #627</li> <li>Remove duplicated headings for docstrings nested in tabs/admonitions (e2123a9 by Perceval Wajsburt, f4a94f7 by Oleh Prypin). Issue #609, PR #610, PR #613</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_11","level":3,"title":"Code Refactoring","text":"<ul> <li>Drop support for MkDocs &lt; 1.4, modernize usages (b61d4d1 by Oleh Prypin). PR #629</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0230-2023-08-28","level":2,"title":"0.23.0 - 2023-08-28","text":"<p>Compare with 0.22.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#breaking-changes_2","level":3,"title":"Breaking Changes","text":"<ul> <li>Removed <code>BaseCollector</code> and <code>BaseRenderer</code> classes: they were merged into the <code>BaseHandler</code> class.</li> <li>Removed the watch feature, as MkDocs now provides it natively.</li> <li>Removed support for <code>selection</code> and <code>rendering</code> keys in YAML blocks: use <code>options</code> instead.</li> <li>Removed support for loading handlers from the <code>mkdocstrings.handler</code> namespace.   Handlers must now be packaged under the <code>mkdocstrings_handlers</code> namespace.</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_6","level":3,"title":"Features","text":"<ul> <li>Register all anchors for each object in the inventory (228fb73 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_10","level":3,"title":"Bug Fixes","text":"<ul> <li>Don't add <code>codehilite</code> CSS class to inline code (7690d41 by Timothée Mazzucotelli).</li> <li>Support cross-references for API docs rendered in top-level index page (b194452 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_12","level":3,"title":"Code Refactoring","text":"<ul> <li>Sort inventories before writing them to disk (9371e9f by Timothée Mazzucotelli).</li> <li>Stop accepting sets as return value of <code>get_anchors</code> (only tuples), to preserve order (2e10374 by Timothée Mazzucotelli).</li> <li>Remove deprecated parts (0a90a47 by Timothée Mazzucotelli).</li> <li>Use proper parameters in <code>Inventory.register</code> method (433c6e0 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0220-2023-05-25","level":2,"title":"0.22.0 - 2023-05-25","text":"<p>Compare with 0.21.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_7","level":3,"title":"Features","text":"<ul> <li>Allow extensions to add templates (cf0af05 by Timothée Mazzucotelli). PR #569</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_13","level":3,"title":"Code Refactoring","text":"<ul> <li>Report inventory loading errors (2c05d78 by Timothée Mazzucotelli). Co-authored-by: Oleh Prypin oleh@pryp.in</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0212-2023-04-06","level":2,"title":"0.21.2 - 2023-04-06","text":"<p>Compare with 0.21.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_11","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix regression with LRU cached method (85efbd2 by Timothée Mazzucotelli). Issue #549</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0211-2023-04-05","level":2,"title":"0.21.1 - 2023-04-05","text":"<p>Compare with 0.21.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_12","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix missing typing-extensions dependency on Python less than 3.10 (bff760b by Timothée Mazzucotelli). Issue #548</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0210-2023-04-05","level":2,"title":"0.21.0 - 2023-04-05","text":"<p>Compare with 0.20.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_8","level":3,"title":"Features","text":"<ul> <li>Expose the full config to handlers (15dacf6 by David Patterson). Issue #501, PR #509</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0200-2023-01-19","level":2,"title":"0.20.0 - 2023-01-19","text":"<p>Compare with 0.19.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_9","level":3,"title":"Features","text":"<ul> <li>Add <code>enabled</code> configuration option (8cf117d by StefanBRas). Issue #478, PR #504</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_13","level":3,"title":"Bug Fixes","text":"<ul> <li>Handle updating Jinja environment of multiple handlers (a6ea80c by David Patterson). Related PR #201, Issue #502, PR #507</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_14","level":3,"title":"Code Refactoring","text":"<ul> <li>Make <code>_load_inventory</code> accept lists as arguments (105ed82 by Sorin Sbarnea). Needed by PR mkdocstrings/python#49, PR #511</li> <li>Remove support for MkDocs &lt; 1.2 (we already depended on MkDocs &gt;= 1.2) (ac963c8 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0191-2022-12-13","level":2,"title":"0.19.1 - 2022-12-13","text":"<p>Compare with 0.19.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_14","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix regular expression for Sphinx inventory parsing (348bdd5 by Luis Michaelis). Issue #496, PR #497</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_15","level":3,"title":"Code Refactoring","text":"<ul> <li>Small fixes to type annotations (9214b74 by Oleh Prypin). PR #470</li> <li>Report usage-based warnings as user-facing messages (03dd7a6 by Oleh Prypin). PR #464</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0190-2022-05-28","level":2,"title":"0.19.0 - 2022-05-28","text":"<p>Compare with 0.18.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#highlights","level":3,"title":"Highlights","text":"<p>We decided to deprecate a few things to pave the way towards a more stable code base, bringing us closer to a v1.</p> <ul> <li>Selection and rendering options are now combined into a single   <code>options</code> key. Using the old keys will emit a deprecation warning.</li> <li>The <code>BaseCollector</code> and <code>BaseRenderer</code> classes are deprecated in favor   of <code>BaseHandler</code>, which merges their functionality. Using the old   classes will emit a deprecation warning.</li> </ul> <p>New versions of the Python handler and the legacy Python handler were also released in coordination with mkdocstrings 0.19. See their respective changelogs: python, python-legacy. Most notably, the Python handler gained the <code>members</code> and <code>filters</code> options that prevented many users to switch to it.</p> <p>mkdocstrings stopped depending directly on the legacy Python handler. It means you now have to explicitely depend on it, directly or through the extra provided by mkdocstrings, if you want to continue using it.</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging-dependencies","level":3,"title":"Packaging / Dependencies","text":"<ul> <li>Stop depending directly on mkdocstrings-python-legacy (9055d58 by Timothée Mazzucotelli). Issue #376</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_10","level":3,"title":"Features","text":"<ul> <li>Pass config file path to handlers (cccebc4 by Timothée Mazzucotelli). Issue #311, PR #425</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_16","level":3,"title":"Code Refactoring","text":"<ul> <li>Support options / deprecated options mix-up (7c71f26 by Timothée Mazzucotelli).</li> <li>Deprecate watch feature in favor of MkDocs' built-in one (c20022e by Timothée Mazzucotelli).</li> <li>Log relative template paths if possible, instead of absolute (91f5f83 by Timothée Mazzucotelli).</li> <li>Deprecate <code>selection</code> and <code>rendering</code> YAML keys (3335310 by Timothée Mazzucotelli). PR #420</li> <li>Deprecate <code>BaseCollector</code> and <code>BaseRenderer</code> (eb822cb by Timothée Mazzucotelli). PR #413</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0181-2022-03-01","level":2,"title":"0.18.1 - 2022-03-01","text":"<p>Compare with 0.18.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_15","level":3,"title":"Bug Fixes","text":"<ul> <li>Don't preemptively register identifiers as anchors (c7ac043 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0180-2022-02-06","level":2,"title":"0.18.0 - 2022-02-06","text":"<p>Compare with 0.17.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#highlights_1","level":3,"title":"Highlights","text":"<ul> <li>Python 3.6 support is dropped.</li> <li>We provide a new, experimental Python handler based on Griffe.   This new handler brings automatic cross-references for every annotation in your code,   including references to third-party libraries' APIs if they provide objects inventories   and you explicitely load them in <code>mkdocs.yml</code>.   See migration notes in the documentation.</li> <li>The \"legacy\" Python handler now lives in its own repository at https://github.com/mkdocstrings/python-legacy.</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging-dependencies_1","level":3,"title":"Packaging / Dependencies","text":"<ul> <li>Add Crystal extra, update Python extras versions (b8222b0 by Timothée Mazzucotelli). PR #374</li> <li>Update autorefs to actually required version (fc6c7f6 by Timothée Mazzucotelli).</li> <li>Drop Python 3.6 support (7205ac6 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_11","level":3,"title":"Features","text":"<ul> <li>Allow unwrapping the <code>&lt;p&gt;</code> tag in <code>convert_markdown</code> filter (5351fc8 by Oleh Prypin). PR #369</li> <li>Support handlers spanning multiple locations (f42dfc6 by Timothée Mazzucotelli). PR #355</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_17","level":3,"title":"Code Refactoring","text":"<ul> <li>Prefix logs with the package name only (6c2b734 by Timothée Mazzucotelli). PR #375</li> <li>Extract the Python handler into its own repository (74371e4 by Timothée Mazzucotelli). PR #356</li> <li>Support Jinja2 3.1 (b377227 by Timothée Mazzucotelli). Issue #360, PR #361</li> <li>Find templates in new and deprecated namespaces (d5d5f18 by Timothée Mazzucotelli). PR #367</li> <li>Support loading handlers from the <code>mkdocstrings_handlers</code> namespace (5c22c6c by Timothée Mazzucotelli). PR #367</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0170-2021-12-27","level":2,"title":"0.17.0 - 2021-12-27","text":"<p>Compare with 0.16.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_12","level":3,"title":"Features","text":"<ul> <li>Add <code>show_signature</code> rendering option (024ee82 by Will Da Silva). Issue #341, PR #342</li> <li>Support Keyword Args and Yields sections (1286427 by Timothée Mazzucotelli). Issue #205 and #324, PR #331</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_16","level":3,"title":"Bug Fixes","text":"<ul> <li>Do minimum work when falling back to re-collecting an object to get its anchor (f6cf570 by Timothée Mazzucotelli). Issue #329, PR #330</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_18","level":3,"title":"Code Refactoring","text":"<ul> <li>Return multiple identifiers from fallback method (78c498c by Timothée Mazzucotelli). Issue mkdocstrings/autorefs#11, PR #350</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0162-2021-10-04","level":2,"title":"0.16.2 - 2021-10-04","text":"<p>Compare with 0.16.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#dependencies_2","level":3,"title":"Dependencies","text":"<ul> <li>Support <code>pymdown-extensions</code> v9.x (0831343 by Ofek Lev and 38b22ec by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0161-2021-09-23","level":2,"title":"0.16.1 - 2021-09-23","text":"<p>Compare with 0.16.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_17","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix ReadTheDocs \"return\" template (598621b by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0160-2021-09-20","level":2,"title":"0.16.0 - 2021-09-20","text":"<p>Compare with 0.15.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_13","level":3,"title":"Features","text":"<ul> <li>Add a rendering option to change the sorting of members (b1fff8b by Joe Rickerby). Issue #114, PR #274</li> <li>Add option to show Python base classes (436f550 by Brian Koropoff). Issue #269, PR #297</li> <li>Support loading external Python inventories in Sphinx format (a8418cb by Oleh Prypin). PR #287</li> <li>Support loading external inventories and linking to them (8b675f4 by Oleh Prypin). PR #277</li> <li>Very basic support for MkDocs theme (974ca90 by Oleh Prypin). PR #272</li> <li>Generate objects inventory (14ed959 and bbd85a9 by Timothée Mazzucotelli). Issue #251, PR #253</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_18","level":3,"title":"Bug Fixes","text":"<ul> <li>Don't render empty code blocks for missing type annotations (d2e9e1e by Oleh Prypin).</li> <li>Fix custom handler not being used (6dcf342 by Timothée Mazzucotelli). Issue #259, PR #263</li> <li>Don't hide <code>setup_commands</code> errors (92418c4 by Gabriel Vîjială). PR #258</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_19","level":3,"title":"Code Refactoring","text":"<ul> <li>Move writing extra files to an earlier stage in the build (3890ab5 by Oleh Prypin). PR #275</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0152-2021-06-09","level":2,"title":"0.15.2 - 2021-06-09","text":"<p>Compare with 0.15.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging","level":3,"title":"Packaging","text":"<ul> <li>MkDocs default schema needs to be obtained differently now (b3e122b by Oleh Prypin). PR #273</li> <li>Compatibility with MkDocs 1.2: livereload isn't guaranteed now (36e8024 by Oleh Prypin). PR #294</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0151-2021-05-16","level":2,"title":"0.15.1 - 2021-05-16","text":"<p>Compare with 0.15.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_19","level":3,"title":"Bug Fixes","text":"<ul> <li>Prevent error during parallel installations (fac2c71 by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_1","level":3,"title":"Packaging","text":"<ul> <li>Support the upcoming major Jinja and MarkupSafe releases (bb4f9de by Oleh Prypin). PR #283</li> <li>Accept a higher version of mkdocs-autorefs (c8de08e by Oleh Prypin). PR #282</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0150-2021-02-28","level":2,"title":"0.15.0 - 2021-02-28","text":"<p>Compare with 0.14.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#breaking-changes_3","level":3,"title":"Breaking Changes","text":"<p>The following items are possible breaking changes:</p> <ul> <li>Cross-linking to arbitrary headings now requires to opt-in to the autorefs plugin,   which is installed as a dependency of mkdocstrings.   See Cross-references to any Markdown heading.</li> <li>mkdocstrings now respects your configured code highlighting method,   so if you are using the CodeHilite extension, the <code>.highlight</code> CSS class in the rendered HTML will become <code>.codehilite</code>.   So make sure to adapt your extra CSS accordingly. Or just switch to using pymdownx.highlight, it's better supported by mkdocstrings anyway.   See Syntax highlighting.</li> <li>Most of the CSS rules that mkdocstrings used to recommend for manual addition, now become mandatory (auto-injected into the site). This shouldn't break any of your styles, but you are welcome to remove the now-redundant lines that you had copied into <code>extra_css</code>, similarly to this diff.</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_14","level":3,"title":"Features","text":"<ul> <li>Nicer-looking error outputs - no tracebacks from mkdocstrings (6baf720 by Oleh Prypin). PR #230</li> <li>Let handlers add CSS to the pages, do so for Python handler (05c7a3f by Oleh Prypin). Issue #189, PR #218</li> <li>Allow linking to an object heading not only by its canonical identifier, but also by its possible aliases (4789950 by Oleh Prypin). PR #217</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_20","level":3,"title":"Bug Fixes","text":"<ul> <li>Propagate the CSS class to inline highlighting as well (c7d80e6 by Oleh Prypin). PR #245</li> <li>Don't double-escape characters in highlighted headings (6357144 by Oleh Prypin). Issue #228, PR #241</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_20","level":3,"title":"Code Refactoring","text":"<ul> <li>Use the autorefs plugin from its new external location (e2d74ef by Oleh Prypin). PR #235</li> <li>Split out Markdown extensions from <code>handlers</code> to <code>handlers.rendering</code> (7533852 by Oleh Prypin). PR #233</li> <li>Theme-agnostic code highlighting, respecting configs (f9ea009 by Oleh Prypin). PR #202</li> <li>Split out autorefs plugin, make it optional (fc67656 by Oleh Prypin). PR #220</li> <li>Remove the extra wrapper div from the final doc (7fe438c by Oleh Prypin). PR #209</li> <li>Don't re-parse the whole subdoc, expose only headings (15f84f9 by Oleh Prypin). PR #209</li> <li>Actually exclude hidden headings from the doc (0fdb082 by Oleh Prypin). PR #209</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0140-2021-01-06","level":2,"title":"0.14.0 - 2021-01-06","text":"<p>Compare with 0.13.6</p> <p>Special thanks to Oleh @oprypin Prypin who did an amazing job (this is a euphemism) at improving mkdocstrings, fixing hard-to-fix bugs with clever solutions, implementing great new features and refactoring the code for better performance and readability! Thanks Oleh!</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_21","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix double code tags (e84d401 by Timothée Mazzucotelli).</li> <li>Don't mutate the original Markdown config for permalinks (8f6b163 by Oleh Prypin).</li> <li>Preserve text immediately before an autodoc (07466fa by Oleh Prypin). PR #207</li> <li>Remove <code>href</code> attributes from headings in templates (d5602ff by Oleh Prypin). PR #204</li> <li>Don't let <code>toc</code> extension append its permalink twice (a154f5c by Oleh Prypin). PR #203</li> <li>Fix undefined entity for <code>&amp;para;</code> (2c29211 by Timothée Mazzucotelli).</li> <li>Make ids of Markdown sub-documents prefixed with the parent item id (d493d33 by Oleh Prypin). Issue #186 and #193, PR #199</li> <li>More lenient regex for data-mkdocstrings-identifier (dcfec8e by Oleh Prypin).</li> <li>Shift Markdown headings according to the current <code>heading_level</code> (13f41ae by Oleh Prypin). Issue #192, PR #195</li> <li>Fix footnotes appearing in all following objects (af24bc2 by Oleh Prypin). Issue #186, PR #195</li> <li>Fix cross-references from the root index page (9c9f2a0 by Oleh Prypin). Issue #184, PR #185</li> <li>Fix incorrect argument name passed to Markdown (10ce502 by Timothée Mazzucotelli).</li> <li>Fix error when a digit immediately follows a code tag (9b92341 by Oleh Prypin). Issue #169, PR #175</li> <li>Detecting paths relative to template directory in logging (a50046b by Oleh Prypin). Issue #166</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_21","level":3,"title":"Code Refactoring","text":"<ul> <li>BlockProcessor already receives strings, use them as such (bcf7da9 by Oleh Prypin).</li> <li>Remove some unused code (8504084 by Oleh Prypin). PR #206</li> <li>Improve XML parsing error handling (ad86410 by Timothée Mazzucotelli).</li> <li>Explicitly use MarkupSafe (6b9ebe7 by Oleh Prypin).</li> <li>Split out the handler cache, expose it through the plugin (6453026 by Oleh Prypin). Issue #179, PR #191</li> <li>Use ChainMap instead of copying dicts (c634d2c by Oleh Prypin). PR #171</li> <li>Rename logging to loggers to avoid confusion (7a119cc by Timothée Mazzucotelli).</li> <li>Simplify logging (409f93e by Timothée Mazzucotelli).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_15","level":3,"title":"Features","text":"<ul> <li>Allow specifying <code>heading_level</code> as a Markdown heading (10efc28 by Oleh Prypin). PR #170</li> <li>Allow any characters in identifiers (7ede68a by Oleh Prypin). PR #174</li> <li>Allow namespace packages for handlers (39b0465 by Timothée Mazzucotelli).</li> <li>Add template debugging/logging (33b32c1 by Timothée Mazzucotelli).</li> <li>Add initial support for the ReadTheDocs theme (1028115 by Timothée Mazzucotelli). Issue #107, PR #159</li> <li>Add option to show type annotations in signatures (f94ce9b by Timothée Mazzucotelli). Issue #106</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_2","level":3,"title":"Packaging","text":"<ul> <li>Accept verions of <code>pytkdocs</code> up to 0.10.x (see changelog).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#performance-improvements_1","level":3,"title":"Performance Improvements","text":"<ul> <li>Call <code>update_env</code> only once per <code>Markdown</code> instance (b198c74 by Oleh Prypin). PR #201</li> <li>Disable Jinja's <code>auto_reload</code> to reduce disk reads (3b28c58 by Oleh Prypin). PR #200</li> <li>Rework autorefs replacement to not re-parse the final HTML (22a9e4b by Oleh Prypin). Issue #187, PR #188</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0136-2020-09-28","level":2,"title":"0.13.6 - 2020-09-28","text":"<p>Compare with 0.13.5</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_22","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix rendering when clicking on hidden toc entries (2af4d31 by Timothée Mazzucotelli). Issue #60.</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0135-2020-09-28","level":2,"title":"0.13.5 - 2020-09-28","text":"<p>Compare with 0.13.4</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_3","level":2,"title":"Packaging","text":"<ul> <li>Accept <code>pytkdocs</code> version up to 0.9.x (changelog).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0134-2020-09-25","level":2,"title":"0.13.4 - 2020-09-25","text":"<p>Compare with 0.13.3</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_23","level":3,"title":"Bug Fixes","text":"<ul> <li>Bring back arbitrary <code>**config</code> to Python handler (fca7d4c by Florimond Manca). Issue #154, PR #155</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0133-2020-09-25","level":2,"title":"0.13.3 - 2020-09-25","text":"<p>Compare with 0.13.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_4","level":3,"title":"Packaging","text":"<ul> <li>Accept <code>pytkdocs</code> version up to 0.8.x (changelog).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0132-2020-09-08","level":2,"title":"0.13.2 - 2020-09-08","text":"<p>Compare with 0.13.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_24","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix relative URLs when <code>use_directory_urls</code> is false (421d189 by Timothée Mazzucotelli). References: #149</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0131-2020-09-03","level":2,"title":"0.13.1 - 2020-09-03","text":"<p>Compare with 0.13.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_25","level":3,"title":"Bug Fixes","text":"<ul> <li>Use relative links for cross-references (9c77f1f by Timothée Mazzucotelli). References: #144, #147</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0130-2020-08-21","level":2,"title":"0.13.0 - 2020-08-21","text":"<p>Compare with 0.12.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_26","level":3,"title":"Bug Fixes","text":"<ul> <li>Accept dashes in module names (fcf79d0 by Timothée Mazzucotelli). References: #140</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_16","level":3,"title":"Features","text":"<ul> <li>Add option to show full path of direct members only (d1b9401 by Aaron Dunmore). References: #134, #136</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_5","level":3,"title":"Packaging","text":"<ul> <li>Accept <code>pymdown-extensions</code> versions up to 0.8.x (see release notes) (178d48d by Hugo van Kemenade). PR #146</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0122-2020-07-24","level":2,"title":"0.12.2 - 2020-07-24","text":"<p>Compare with 0.12.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_6","level":3,"title":"Packaging","text":"<ul> <li>Accept <code>pytkdocs</code> version up to 0.7.x (changelog).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0121-2020-07-07","level":2,"title":"0.12.1 - 2020-07-07","text":"<p>Compare with 0.12.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_27","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix HTML-escaped sequence parsing as XML (db297f1 by Timothée Mazzucotelli).</li> <li>Allow running mkdocs from non-default interpreter (283dd7b by Jared Khan).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0120-2020-06-14","level":2,"title":"0.12.0 - 2020-06-14","text":"<p>Compare with 0.11.4</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_17","level":3,"title":"Features","text":"<ul> <li>Support attributes section in Google-style docstrings (8300253 by Timothée Mazzucotelli). References: #88</li> <li>Support examples section in Google-style docstrings (650c754 by Iago González). References: #112</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_7","level":3,"title":"Packaging","text":"<ul> <li>Accept <code>pytkdocs</code> version up to 0.6.x (changelog).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0114-2020-06-08","level":2,"title":"0.11.4 - 2020-06-08","text":"<p>Compare with 0.11.3</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_8","level":3,"title":"Packaging","text":"<ul> <li>Accept <code>pytkdocs</code> version up to 0.5.x (changelog).   If it breaks your docs, please open issues on <code>pytkdocs</code>' bug-tracker,   or pin <code>pytkdocs</code> version to while waiting for bug fixes &lt;0.5.0 .</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0113-2020-06-07","level":2,"title":"0.11.3 - 2020-06-07","text":"<p>Compare with 0.11.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_28","level":3,"title":"Bug Fixes","text":"<ul> <li>Support custom theme directory configuration (1243cf6 by Abhishek Thakur). References: #120, #121</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0112-2020-05-20","level":2,"title":"0.11.2 - 2020-05-20","text":"<p>Compare with 0.11.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_9","level":3,"title":"Packaging","text":"<ul> <li>Increase <code>pytkdocs</code> version range to accept 0.4.0   (changelog).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0111-2020-05-14","level":2,"title":"0.11.1 - 2020-05-14","text":"<p>Compare with 0.11.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_29","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix integration with mkdocs logging une bonne fois pour toute (3293cbf by Timothée Mazzucotelli).</li> <li>Discard setup commands stdout (ea44cea by Timothée Mazzucotelli). References: #91</li> <li>Use the proper python executable to start subprocesses (9fe3b39 by Reece Dunham). References: #91, #103</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0110-2020-04-23","level":2,"title":"0.11.0 - 2020-04-23","text":"<p>Compare with 0.10.3</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_30","level":3,"title":"Bug Fixes","text":"<ul> <li>Properly raise on errors (respect strict mode) (2097208 by Timothée Mazzucotelli). Related issues/PRs: #86</li> <li>Hook properly to MkDocs logging (b23daed by Timothée Mazzucotelli). Related issues/PRs: #86</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_18","level":3,"title":"Features","text":"<ul> <li>Add <code>setup_commands</code> option to python handler (599f8e5 by Ross Mechanic). Related issues/PRs: #89, #90</li> <li>Add option to allow overriding templates (7360021 by Mikaël Capelle). Related issues/PRs: #59, #82</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0103-2020-04-10","level":2,"title":"0.10.3 - 2020-04-10","text":"<p>Compare with 0.10.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_31","level":3,"title":"Bug Fixes","text":"<ul> <li>Handle <code>site_url</code> not being defined (9fb4a9b by Timothée Mazzucotelli). Related issues/PRs: #77</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_10","level":3,"title":"Packaging","text":"<p>This version increases the accepted range of versions for the <code>pytkdocs</code> dependency to <code>&gt;=0.2.0, &lt;0.4.0</code>. The <code>pytkdocs</code> project just released version 0.3.0 which:</p> <ul> <li>adds support for complex markup in docstrings sections items descriptions</li> <li>adds support for different indentations in docstrings sections (tabulations or less/more than 4 spaces)</li> <li>fixes docstring parsing for arguments whose names start with <code>*</code>, like <code>*args</code> and <code>**kwargs</code></li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0102-2020-04-07","level":2,"title":"0.10.2 - 2020-04-07","text":"<p>Compare with 0.10.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#packaging_11","level":3,"title":"Packaging","text":"<p>This version increases the accepted range of versions for the <code>pymdown-extensions</code> dependency, as well as for the <code>mkdocs-material</code> development dependency. Indeed, both these projects recently released major versions 7 and 5 respectively. Users who wish to use these new versions will be able to. See issue #74.</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0101-2020-04-03","level":2,"title":"0.10.1 - 2020-04-03","text":"<p>Compare with 0.10.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_32","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix jinja2 error for jinja2 &lt; 2.11 (387f970 by Timothée Mazzucotelli). Related issues/PRs: #67, #72</li> <li>Fix missing dependency pymdown-extensions (648b99d by Timothée Mazzucotelli). Related issues/PRs: #66</li> <li>Fix heading level of hidden toc entries (475cc62 by Timothée Mazzucotelli). Related issues/PRs: #65</li> <li>Fix rendering signatures containing keyword_only (c6c5add by Timothée Mazzucotelli). Related issues/PRs: #68</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#0100-2020-03-27","level":2,"title":"0.10.0 - 2020-03-27","text":"<p>Compare with 0.9.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_19","level":3,"title":"Features","text":"<ul> <li>Prepare for new <code>pytkdocs</code> version (336421a).   Add options <code>filters</code> and <code>members</code> to the Python collector to reflect the new <code>pytkdocs</code> options.</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#091-2020-03-21","level":2,"title":"0.9.1 - 2020-03-21","text":"<p>Compare with 0.9.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_33","level":3,"title":"Bug fixes","text":"<ul> <li>Fix cross-references when deploying to GitHub pages (36f804b).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#090-2020-03-21","level":2,"title":"0.9.0 - 2020-03-21","text":"<p>Compare with 0.8.0</p> <p>This version is a big refactor. We will just list the new features without pointing to particular commits. The documentation rendering looks slightly different, and should be better than before. No identified breaking changes for end-users.</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_20","level":3,"title":"Features","text":"<ul> <li>Language agnostic: we moved the code responsible for loading Python documentation into a new project,   <code>pytkdocs</code>, and implemented a \"handlers\" logic, effectively allowing to   support any given language. Waiting for your handlers contributions !</li> <li>Multiple themes support: handlers can offer templates for multiple <code>mkdocs</code> themes.</li> <li>Better cross-references: cross-references now not only work between documented objects (between all languages,   given the objects' identifiers are unique), but also for every heading of your Markdown pages.</li> <li>Configuration options: the rendering of Python documentation can now be configured,   (globally and locally thanks to the handlers system).   Also see the recommended CSS.</li> <li>Proper logging messages: <code>mkdocstrings</code> now logs debug, warning and error messages, useful when troubleshooting.</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_34","level":3,"title":"Bug fixes","text":"<ul> <li>Various fixes and better error handling.</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#080-2020-03-04","level":2,"title":"0.8.0 - 2020-03-04","text":"<p>Compare with 0.7.2</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#breaking-changes_4","level":3,"title":"Breaking Changes","text":"<ul> <li>Be compatible with Mkdocs &gt;= 1.1 (5a974a4).   This is a breaking change as we're not compatible with versions of Mkdocs below 1.1 anymore.   If you cannot upgrade Mkdocs to 1.1, pin mkdocstrings' version to 0.7.2.</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#072-2020-03-04","level":2,"title":"0.7.2 - 2020-03-04","text":"<p>Compare with 0.7.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_35","level":3,"title":"Bug Fixes","text":"<ul> <li>Catch <code>OSError</code> when trying to get source lines (8e8d604).</li> <li>Do not render signature empty sentinel (16dfd73).</li> <li>Fix for nested classes and their attributes (7fef903).</li> <li>Fix <code>relative_file_path</code> method (52715ad).</li> <li>Wrap file path in backticks to escape it (2525f39).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#071-2020-02-18","level":2,"title":"0.7.1 - 2020-02-18","text":"<p>Compare with 0.7.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_36","level":3,"title":"Bug Fixes","text":"<ul> <li>Replace literal slash with os.sep for Windows compatibility (70f9af5).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#070-2020-01-13","level":2,"title":"0.7.0 - 2020-01-13","text":"<p>Compare with 0.6.1</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_37","level":3,"title":"Bug Fixes","text":"<ul> <li>Don't mark args or kwargs as required (4049d6f).</li> <li>Filter submodules (7b11095).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_22","level":3,"title":"Code Refactoring","text":"<ul> <li>Don't guess lang in generated docs (db4f60a).</li> <li>Render at HTML step with custom markdown converter (9b5a3e1).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_21","level":3,"title":"Features","text":"<ul> <li>Change forward ref to ref, fix optional unions (2f0bfaa).</li> <li>Discover package submodules (231062a).</li> <li>Implement watched source code (hacks) (4a67953).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#061-2020-01-02","level":2,"title":"0.6.1 - 2020-01-02","text":"<p>Compare with 0.6.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_38","level":3,"title":"Bug Fixes","text":"<ul> <li>Break docstring discarding loop if found (5a17fec).</li> <li>Fix discarding docstring (143f7cb).</li> <li>Fix getting annotation from nodes (ecde72b).</li> <li>Fix various things (affbf06).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_23","level":3,"title":"Code Refactoring","text":"<ul> <li>Break as soon as we find the same attr in a parent class while trying to discard the docstring (65d7908).</li> <li>Split Docstring.parse method to improve readability (2226e2d).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#060-2019-12-28","level":2,"title":"0.6.0 - 2019-12-28","text":"<p>Compare with 0.5.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#bug-fixes_39","level":3,"title":"Bug Fixes","text":"<ul> <li>Fix GenericMeta import error on Python 3.7+ (febf2b9).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#code-refactoring_24","level":3,"title":"Code Refactoring","text":"<ul> <li>More classes. Still ugly code though :'( (f41c119).</li> <li>Split into more modules (f1872a4).</li> <li>Use Object subclasses (40dd106).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#050-2019-12-22","level":2,"title":"0.5.0 - 2019-12-22","text":"<p>Compare with 0.4.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_22","level":3,"title":"Features","text":"<ul> <li>Use divs in HTML contents to ease styling (2a36a0e).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#040-2019-12-22","level":2,"title":"0.4.0 - 2019-12-22","text":"<p>Compare with 0.3.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_23","level":3,"title":"Features","text":"<ul> <li>Parse docstrings Google-style blocks, get types from signature (5af0c7b).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#030-2019-12-21","level":2,"title":"0.3.0 - 2019-12-21","text":"<p>Compare with 0.2.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#features_24","level":3,"title":"Features","text":"<ul> <li>Allow object referencing in docstrings (2dd50c0).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#020-2019-12-15","level":2,"title":"0.2.0 - 2019-12-15","text":"<p>Compare with 0.1.0</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#misc","level":3,"title":"Misc","text":"<ul> <li>Refactor, features, etc. (111fa85).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#010-2019-12-12","level":2,"title":"0.1.0 - 2019-12-12","text":"<p>Compare with first commit</p>","path":["Home","Changelog"],"tags":[]},{"location":"changelog/#misc_1","level":3,"title":"Misc","text":"<ul> <li>Clean up (delete unused files) (c227043).</li> <li>Clean up unused makefile rules (edc01e9).</li> <li>Initial commit (f1dd8fb).</li> <li>Update readme (ae56bdd).</li> <li>Add plugin (6ed5cb1).</li> <li>First PoC, needs better theming (18a00b9).</li> <li>Get attributes docstrings (7838fff).</li> <li>Refactor (f68f1a8).</li> </ul>","path":["Home","Changelog"],"tags":[]},{"location":"code_of_conduct/","level":1,"title":"Contributor Covenant Code of Conduct","text":"","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#our-pledge","level":2,"title":"Our Pledge","text":"<p>We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.</p> <p>We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#our-standards","level":2,"title":"Our Standards","text":"<p>Examples of behavior that contributes to a positive environment for our community include:</p> <ul> <li>Demonstrating empathy and kindness toward other people</li> <li>Being respectful of differing opinions, viewpoints, and experiences</li> <li>Giving and gracefully accepting constructive feedback</li> <li>Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience</li> <li>Focusing on what is best not just for us as individuals, but for the overall community</li> </ul> <p>Examples of unacceptable behavior include:</p> <ul> <li>The use of sexualized language or imagery, and sexual attention or advances of any kind</li> <li>Trolling, insulting or derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or email address, without their explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a professional setting</li> </ul>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#enforcement-responsibilities","level":2,"title":"Enforcement Responsibilities","text":"<p>Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.</p> <p>Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#scope","level":2,"title":"Scope","text":"<p>This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#enforcement","level":2,"title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at dev@pawamoy.fr. All complaints will be reviewed and investigated promptly and fairly.</p> <p>All community leaders are obligated to respect the privacy and security of the reporter of any incident.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#enforcement-guidelines","level":2,"title":"Enforcement Guidelines","text":"<p>Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#1-correction","level":3,"title":"1. Correction","text":"<p>Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.</p> <p>Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#2-warning","level":3,"title":"2. Warning","text":"<p>Community Impact: A violation through a single incident or series of actions.</p> <p>Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#3-temporary-ban","level":3,"title":"3. Temporary Ban","text":"<p>Community Impact: A serious violation of community standards, including sustained inappropriate behavior.</p> <p>Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#4-permanent-ban","level":3,"title":"4. Permanent Ban","text":"<p>Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.</p> <p>Consequence: A permanent ban from any sort of public interaction within the community.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"code_of_conduct/#attribution","level":2,"title":"Attribution","text":"<p>This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.</p> <p>Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.</p> <p>For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.</p>","path":["Development","Code of Conduct"],"tags":[]},{"location":"contributing/","level":1,"title":"Contributing","text":"<p>Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.</p> <p>Please always create an issue before working on a new feature or a bug fix, so that we can discuss the implementation and make sure that your work will be merged.</p>","path":["Development","Contributing"],"tags":[]},{"location":"contributing/#environment-setup","level":2,"title":"Environment setup","text":"<p>Nothing easier!</p> <p>Fork and clone the repository. The project uses dynamic versioning, so to get the correct package version when building, make sure to pull Git tags:</p> <pre><code>cd mkdocstrings\n\n# Assuming you authenticate with SSH.\ngit remote add upstream git@github.com:mkdocstrings/mkdocstrings\ngit pull upstream --tags\n</code></pre> <p>Then:</p> <pre><code>make setup\n</code></pre> <p>Note</p> <p>If it fails for some reason, you'll need to install uv manually.</p> <p>You can install it with:</p> <pre><code>curl -LsSf https://astral.sh/uv/install.sh | sh\n</code></pre> <p>Now you can try running <code>make setup</code> again, or simply <code>uv sync</code>.</p> <p>You now have the dependencies installed.</p> <p>Run <code>make help</code> to see all the available actions!</p>","path":["Development","Contributing"],"tags":[]},{"location":"contributing/#tasks","level":2,"title":"Tasks","text":"<p>The entry-point to run commands and tasks is the <code>make</code> Python script, located in the <code>scripts</code> directory. Try running <code>make</code> to show the available commands and tasks. The commands do not need the Python dependencies to be installed, while the tasks do. The cross-platform tasks are written in Python, thanks to duty.</p> <p>If you work in VSCode, we provide an action to configure VSCode for the project.</p>","path":["Development","Contributing"],"tags":[]},{"location":"contributing/#development","level":2,"title":"Development","text":"<p>As usual:</p> <ol> <li>create a new branch: <code>git switch -c feature-or-bugfix-name</code></li> <li>edit the code and/or the documentation</li> </ol> <p>Before committing:</p> <ol> <li>run <code>make format</code> to auto-format the code</li> <li>run <code>make check</code> to check everything (fix any warning)</li> <li>run <code>make test</code> to run the tests (fix any issue)</li> <li>if you updated the documentation or the project dependencies:<ol> <li>run <code>make docs</code></li> <li>go to http://localhost:8000 and check that everything looks good</li> </ol> </li> <li>follow our commit message convention</li> </ol> <p>If you are unsure about how to fix or ignore a warning, just let the continuous integration fail, and we will help you during review.</p> <p>Don't bother updating the changelog, we will take care of this.</p>","path":["Development","Contributing"],"tags":[]},{"location":"contributing/#commit-message-convention","level":2,"title":"Commit message convention","text":"<p>Commit messages must follow our convention based on the Angular style or the Karma convention:</p> <pre><code>&lt;type&gt;[(scope)]: Subject\n\n[Body]\n</code></pre> <p>Subject and body must be valid Markdown. Subject must have proper casing (uppercase for first letter if it makes sense), but no dot at the end, and no punctuation in general.</p> <p>Scope and body are optional. Type can be:</p> <ul> <li><code>build</code>: About packaging, building wheels, etc.</li> <li><code>chore</code>: About packaging or repo/files management.</li> <li><code>ci</code>: About Continuous Integration.</li> <li><code>deps</code>: Dependencies update.</li> <li><code>docs</code>: About documentation.</li> <li><code>feat</code>: New feature.</li> <li><code>fix</code>: Bug fix.</li> <li><code>perf</code>: About performance.</li> <li><code>refactor</code>: Changes that are not features or bug fixes.</li> <li><code>style</code>: A change in code style/format.</li> <li><code>tests</code>: About tests.</li> </ul> <p>If you write a body, please add trailers at the end (for example issues and PR references, or co-authors), without relying on GitHub's flavored Markdown:</p> <pre><code>Body.\n\nIssue #10: https://github.com/namespace/project/issues/10\nRelated to PR namespace/other-project#15: https://github.com/namespace/other-project/pull/15\n</code></pre> <p>These \"trailers\" must appear at the end of the body, without any blank lines between them. The trailer title can contain any character except colons <code>:</code>. We expect a full URI for each trailer, not just GitHub autolinks (for example, full GitHub URLs for commits and issues, not the hash or the #issue-number).</p> <p>We do not enforce a line length on commit messages summary and body, but please avoid very long summaries, and very long lines in the body, unless they are part of code blocks that must not be wrapped.</p>","path":["Development","Contributing"],"tags":[]},{"location":"contributing/#pull-requests-guidelines","level":2,"title":"Pull requests guidelines","text":"<p>Link to any related issue in the Pull Request message.</p> <p>During the review, we recommend using fixups:</p> <pre><code># SHA is the SHA of the commit you want to fix\ngit commit --fixup=SHA\n</code></pre> <p>Once all the changes are approved, you can squash your commits:</p> <pre><code>git rebase -i --autosquash main\n</code></pre> <p>And force-push:</p> <pre><code>git push -f\n</code></pre> <p>If this seems all too complicated, you can push or force-push each new commit, and we will squash them ourselves if needed, before merging.</p>","path":["Development","Contributing"],"tags":[]},{"location":"credits/","level":1,"title":"Credits","text":"","path":["Home","Credits"],"tags":[]},{"location":"credits/#exec-1--credits","level":1,"title":"Credits","text":"<p>These projects were used to build mkdocstrings. Thank you!</p> <p>Python | uv | copier-uv</p>","path":["Home","Credits"],"tags":[]},{"location":"credits/#exec-1--runtime-dependencies","level":3,"title":"Runtime dependencies","text":"Project Summary Version (accepted) Version (last resolved) License click Composable command line interface toolkit <code>&gt;=8.1.8, &gt;=7.0</code> <code>8.3.2</code> BSD-3-Clause colorama Cross-platform colored terminal text. <code>&gt;=0.4</code> <code>0.4.6</code> BSD License ghp-import Copy your docs directly to the gh-pages branch. <code>&gt;=2.1, &gt;=1.0</code> <code>2.1.0</code> Apache Software License griffelib Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API. <code>&gt;=2.0, ==2.0.2</code> <code>2.0.2</code> ISC Jinja2 A very fast and expressive template engine. <code>&gt;=3.1, &gt;=3.0</code> <code>3.1.6</code> BSD License Markdown Python implementation of John Gruber's Markdown. <code>&gt;=3.7, &gt;=3.6</code> <code>3.10.2</code> BSD-3-Clause MarkupSafe Safely add untrusted strings to HTML/XML markup. <code>&gt;=2.0, &gt;=1.1</code> <code>3.0.3</code> BSD-3-Clause mergedeep A deep merge function for 🐍. <code>&gt;=1.3.4</code> <code>1.3.4</code> MIT License mkdocs Project documentation with Markdown. <code>&gt;=1.6</code> <code>1.6.1</code> BSD-2-Clause mkdocs-autorefs Automatically link across pages in MkDocs. <code>&gt;=1.4</code> <code>1.4.4</code> ISC mkdocs-get-deps An extra command for MkDocs that infers required PyPI packages from <code>plugins</code> in mkdocs.yml <code>&gt;=0.2.0</code> <code>0.2.2</code> MIT mkdocstrings-python A Python handler for mkdocstrings. <code>&gt;=1.16.2</code> <code>2.0.3</code> ISC packaging Core utilities for Python packages <code>&gt;=24.1, &gt;=20.5</code> <code>26.1</code> Apache-2.0 OR BSD-2-Clause pathspec Utility library for gitignore style pattern matching of file paths. <code>&gt;=0.11.1</code> <code>1.0.4</code> Mozilla Public License 2.0 (MPL 2.0) platformdirs A small Python package for determining appropriate platform-specific dirs, e.g. a <code>user data dir</code>. <code>&gt;=4.4, &gt;=2.2.0</code> <code>4.9.6</code> MIT pymdown-extensions Extension pack for Python Markdown. <code>&gt;=9, &gt;=6.3</code> <code>10.21.2</code> MIT python-dateutil Extensions to the standard Python datetime module <code>&gt;=2.8.1</code> <code>2.9.0.post0</code> BSD License + Apache Software License PyYAML YAML parser and emitter for Python <code>&gt;=6.0.2</code> <code>6.0.3</code> MIT pyyaml_env_tag A custom YAML tag for referencing environment variables in YAML files. <code>&gt;=0.1</code> <code>1.1</code> MIT six Python 2 and 3 compatibility utilities <code>&gt;=1.5</code> <code>1.17.0</code> MIT typing_extensions Backported and Experimental Type Hints for Python 3.9+ <code>&gt;=4.0</code> <code>4.15.0</code> PSF-2.0 watchdog Filesystem events monitoring <code>&gt;=2.0</code> <code>6.0.0</code> Apache-2.0","path":["Home","Credits"],"tags":[]},{"location":"credits/#exec-1--development-dependencies","level":3,"title":"Development dependencies","text":"Project Summary Version (accepted) Version (last resolved) License ansimarkup Produce colored terminal text with an xml-like markup <code>~=1.4</code> <code>1.5.0</code> Revised BSD License cappa Declarative CLI argument parser. <code>&gt;=0.29</code> <code>0.31.0</code> ? certifi Python package for providing Mozilla's CA Bundle. <code>&gt;=2023.5.7</code> <code>2026.2.25</code> MPL-2.0 cffi Foreign Function Interface for Python calling C code. <code>&gt;=1.14</code> <code>2.0.0</code> MIT charset-normalizer The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet. <code>&gt;=2, &lt;4</code> <code>3.4.7</code> MIT click Composable command line interface toolkit <code>&gt;=8.1.8, &gt;=7.0</code> <code>8.3.2</code> BSD-3-Clause colorama Cross-platform colored terminal text. <code>&gt;=0.4</code> <code>0.4.6</code> BSD License coverage Code coverage measurement for Python <code>&gt;=7.10.6</code> <code>7.13.5</code> Apache-2.0 cryptography cryptography is a package which provides cryptographic recipes and primitives to Python developers. <code>&gt;=2.0</code> <code>46.0.7</code> Apache-2.0 OR BSD-3-Clause deepmerge A toolset for deeply merging Python dictionaries. <code>&gt;=2.0</code> <code>2.0</code> MIT Licence dirty-equals Doing dirty (but extremely useful) things with equals. <code>&gt;=0.9</code> <code>0.11</code> MIT docutils Docutils -- Python Documentation Utilities <code>&gt;=0.21.2</code> <code>0.22.4</code> Public Domain + BSD License + GNU General Public License (GPL) duty A simple task runner. <code>&gt;=1.6</code> <code>1.9.0</code> ISC execnet execnet: rapid multi-Python deployment <code>&gt;=2.1</code> <code>2.1.2</code> MIT failprint Run a command, print its output only if it fails. <code>&gt;=1.0.5</code> <code>1.1.0</code> ISC ghp-import Copy your docs directly to the gh-pages branch. <code>&gt;=2.1, &gt;=1.0</code> <code>2.1.0</code> Apache Software License git-changelog Automatic Changelog generator using Jinja2 templates. <code>&gt;=2.5</code> <code>2.9.3</code> ISC griffe Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API. <code>&gt;=2.0</code> <code>2.0.2</code> ISC griffecli Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API. <code>==2.0.2</code> <code>2.0.2</code> ISC griffelib Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API. <code>&gt;=2.0, ==2.0.2</code> <code>2.0.2</code> ISC humanize Python humanize utilities <code>&gt;=4.9</code> <code>4.15.0</code> MIT id A tool for generating OIDC identities <code>1.6.1</code> Apache Software License idna Internationalized Domain Names in Applications (IDNA) <code>&gt;=2.5, &lt;4</code> <code>3.11</code> BSD-3-Clause iniconfig brain-dead simple config-ini parsing <code>&gt;=1.0.1</code> <code>2.3.0</code> MIT jaraco.classes Utility functions for Python class constructs <code>3.4.0</code> MIT License jaraco.context Useful decorators and context managers <code>6.1.2</code> MIT jaraco.functools Functools like those found in stdlib <code>4.4.0</code> MIT jeepney Low-level, pure Python DBus protocol wrapper. <code>&gt;=0.4.2</code> <code>0.9.0</code> MIT Jinja2 A very fast and expressive template engine. <code>&gt;=3.1, &gt;=3.0</code> <code>3.1.6</code> BSD License keyring Store and access your passwords safely. <code>&gt;=21.2.0</code> <code>25.7.0</code> MIT Markdown Python implementation of John Gruber's Markdown. <code>&gt;=3.7, &gt;=3.6</code> <code>3.10.2</code> BSD-3-Clause markdown-callouts Markdown extension: a classier syntax for admonitions <code>&gt;=0.4</code> <code>0.4.0</code> MIT markdown-exec Utilities to execute code blocks in Markdown files. <code>&gt;=1.8</code> <code>1.12.1</code> ISC markdown-it-py Python port of markdown-it. Markdown parsing, done right! <code>&gt;=2.2.0</code> <code>4.0.0</code> MIT License MarkupSafe Safely add untrusted strings to HTML/XML markup. <code>&gt;=2.0, &gt;=1.1</code> <code>3.0.3</code> BSD-3-Clause mdurl Markdown URL utilities <code>~=0.1</code> <code>0.1.2</code> MIT License more-itertools More routines for operating on iterables, beyond itertools <code>11.0.2</code> MIT nh3 Python binding to Ammonia HTML sanitizer Rust crate <code>&gt;=0.2.14</code> <code>0.3.4</code> MIT packaging Core utilities for Python packages <code>&gt;=24.1, &gt;=20.5</code> <code>26.1</code> Apache-2.0 OR BSD-2-Clause platformdirs A small Python package for determining appropriate platform-specific dirs, e.g. a <code>user data dir</code>. <code>&gt;=4.4, &gt;=2.2.0</code> <code>4.9.6</code> MIT pluggy plugin and hook calling mechanisms for python <code>&gt;=1.2</code> <code>1.6.0</code> MIT ptyprocess Run a subprocess in a pseudo terminal <code>~=0.6</code> <code>0.7.0</code> ISC License (ISCL) pycparser C parser in Python <code>3.0</code> BSD-3-Clause Pygments Pygments is a syntax highlighting package written in Python. <code>&gt;=2.20</code> <code>2.20.0</code> BSD-2-Clause pymdown-extensions Extension pack for Python Markdown. <code>&gt;=9, &gt;=6.3</code> <code>10.21.2</code> MIT pytest pytest: simple powerful testing with Python <code>&gt;=8.2</code> <code>9.0.3</code> MIT pytest-cov Pytest plugin for measuring coverage. <code>&gt;=5.0</code> <code>7.1.0</code> MIT pytest-randomly Pytest plugin to randomly order tests and control random.seed. <code>&gt;=3.15</code> <code>4.0.1</code> MIT pytest-xdist pytest xdist plugin for distributed testing, most importantly across multiple CPUs <code>&gt;=3.6</code> <code>3.8.0</code> MIT python-dateutil Extensions to the standard Python datetime module <code>&gt;=2.8.1</code> <code>2.9.0.post0</code> BSD License + Apache Software License PyYAML YAML parser and emitter for Python <code>&gt;=6.0.2</code> <code>6.0.3</code> MIT readme_renderer readme_renderer is a library for rendering readme descriptions for Warehouse <code>&gt;=35.0</code> <code>44.0</code> Apache License, Version 2.0 requests Python HTTP for Humans. <code>&gt;=2.20</code> <code>2.33.1</code> Apache-2.0 requests-toolbelt A utility belt for advanced users of python-requests <code>&gt;=0.8.0, !=0.9.0</code> <code>1.0.0</code> Apache 2.0 rfc3986 Validating URI References per RFC 3986 <code>&gt;=1.4.0</code> <code>2.0.0</code> Apache 2.0 rich Render rich text, tables, progress bars, syntax highlighting, markdown and more to the terminal <code>&gt;=12.0.0</code> <code>15.0.0</code> MIT ruff An extremely fast Python linter and code formatter, written in Rust. <code>&gt;=0.4</code> <code>0.15.10</code> MIT SecretStorage Python bindings to FreeDesktop.org Secret Service API <code>&gt;=3.2</code> <code>3.5.0</code> BSD-3-Clause semver Python helper for Semantic Versioning (https://semver.org) <code>&gt;=3.0</code> <code>3.0.4</code> BSD License six Python 2 and 3 compatibility utilities <code>&gt;=1.5</code> <code>1.17.0</code> MIT twine Collection of utilities for publishing packages on PyPI <code>&gt;=5.1</code> <code>6.2.0</code> Apache-2.0 ty An extremely fast Python type checker, written in Rust. <code>&gt;=0.0.14</code> <code>0.0.30</code> MIT License type-lens type-lens is a Python template project designed to simplify the setup of a new project. <code>&gt;=0.2.5</code> <code>0.2.6</code> MIT types-Markdown Typing stubs for Markdown <code>&gt;=3.6</code> <code>3.10.2.20260408</code> Apache-2.0 types-PyYAML Typing stubs for PyYAML <code>&gt;=6.0</code> <code>6.0.12.20260408</code> Apache-2.0 typing_extensions Backported and Experimental Type Hints for Python 3.9+ <code>&gt;=4.0</code> <code>4.15.0</code> PSF-2.0 urllib3 HTTP library with thread-safe connection pooling, file post, and more. <code>&gt;=1.26.0</code> <code>2.6.3</code> MIT yore Manage legacy code with comments. <code>&gt;=0.3.3</code> <code>0.4.7</code> ISC zensical A modern static site generator built by the creators of Material for MkDocs <code>&gt;=0.0.21</code> <code>0.0.33</code> MIT <p>More credits from the author</p>","path":["Home","Credits"],"tags":[]},{"location":"license/","level":1,"title":"License","text":"<pre><code>ISC License\n\nCopyright (c) 2019, Timothée Mazzucotelli and contributors\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted, provided that the above\ncopyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES\nWITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF\nMERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR\nANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES\nWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN\nACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF\nOR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.\n</code></pre>","path":["Home","License"],"tags":[]},{"location":"recipes/","level":1,"title":"Recipes","text":"<p>On this page you will find various recipes, tips and tricks for mkdocstrings and more generally Markdown documentation.</p>","path":["Usage","Guides","Recipes"],"tags":[]},{"location":"recipes/#automatic-code-reference-pages","level":2,"title":"Automatic code reference pages","text":"<p>mkdocs-autoapi and mkdocs-api-autonav are MkDocs plugins that automatically generate API documentation from your project's source code. They were inspired by the recipe below</p> <p>mkdocstrings allows to inject documentation for any object into Markdown pages. But as the project grows, it quickly becomes quite tedious to keep the autodoc instructions, or even the dedicated Markdown files in sync with all your source files and objects.</p> <p>In this recipe, we will iteratively automate the process of generating these pages at each build of the documentation.</p> <p>Let say you have a project called <code>project</code>. This project has a lot of source files, or modules, which live in the <code>src</code> folder:</p> <pre><code>repo/\n    src/\n        project/\n            lorem\n            ipsum\n            dolor\n            sit\n            amet\n</code></pre> <p>Without an automatic process, you will have to manually create a Markdown page for each one of these modules, with the corresponding autodoc instruction, for example <code>project.lorem</code>, and also add entry in MkDocs' navigation option (<code>nav</code> in <code>mkdocs.yml</code>). With a lot of modules, this is quickly getting cumbersome.</p> <p>Lets fix that.</p>","path":["Usage","Guides","Recipes"],"tags":[]},{"location":"recipes/#generate-pages-on-the-fly","level":3,"title":"Generate pages on-the-fly","text":"<p>In this recipe, we suggest to use the mkdocs-gen-files plugin. This plugin exposes utilities to generate files at build time. These files won't be written to the docs directory: you don't have to track and version them. They are transparently generated each time you build your docs. This is perfect for our use-case!</p> <p>Add <code>mkdocs-gen-files</code> to your project's docs dependencies, and configure it like so:</p> mkdocs.yml<pre><code>plugins:\n- search  # (1)!\n- gen-files:\n    scripts:\n    - scripts/gen_ref_pages.py  # (2)!\n- mkdocstrings\n</code></pre> <ol> <li>Don't forget to load the <code>search</code> plugin when redefining the <code>plugins</code> item.</li> <li>The magic happens here, see below how it works.</li> </ol> <p>mkdocs-gen-files is able to run Python scripts at build time. The Python script that we will execute lives in a scripts folder, and is named <code>gen_ref_pages.py</code>, like \"generate code reference pages\".</p> <pre><code>repo/\n    docs/\n        index.md\n    scripts/\n        gen_ref_pages.py\n    src/\n        project/\n    mkdocs.yml\n</code></pre> scripts/gen_ref_pages.py<pre><code>\"\"\"Generate the code reference pages.\"\"\"\n\nfrom pathlib import Path\n\nimport mkdocs_gen_files\n\nroot = Path(__file__).parent.parent\nsrc = root / \"src\"  # (1)!\n\nfor path in sorted(src.rglob(\"*.py\")):  # (2)!\n    module_path = path.relative_to(src).with_suffix(\"\")  # (3)!\n    doc_path = path.relative_to(src).with_suffix(\".md\")  # (4)!\n    full_doc_path = Path(\"reference\", doc_path)  # (5)!\n\n    parts = tuple(module_path.parts)\n\n    if parts[-1] == \"__init__\":  # (6)!\n        parts = parts[:-1]\n    elif parts[-1] == \"__main__\":\n        continue\n\n    with mkdocs_gen_files.open(full_doc_path, \"w\") as fd:  # (7)!\n        identifier = \".\".join(parts)  # (8)!\n        print(\"::: \" + identifier, file=fd)  # (9)!\n\n    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))  # (10)!\n</code></pre> <ol> <li>It's important to build a path relative to the script itself,    to make it possible to build the docs with MkDocs'    <code>-f</code> option.</li> <li>Here we recursively list all <code>.py</code> files, but you can adapt the code to list    files with other extensions of course, supporting other languages than Python.</li> <li>The module path will look like <code>project/lorem</code>.    It will be used to build the mkdocstrings autodoc identifier.</li> <li>This is the partial path of the Markdown page for the module.</li> <li>This is the full path of the Markdown page within the docs.    Here we put all reference pages into a <code>reference</code> folder.</li> <li>This part is only relevant for Python modules. We skip <code>__main__</code> modules and    remove <code>__init__</code> from the module parts as it's implicit during imports.</li> <li>Magic! Add the file to MkDocs pages, without actually writing it in the docs folder.</li> <li>Build the autodoc identifier. Here we document Python modules, so the identifier    is a dot-separated path, like <code>project.lorem</code>.</li> <li>Actually write to the magic file.</li> <li>We can even set the <code>edit_uri</code> on the pages.</li> </ol> <p>Note</p> <p> It is important to look out for correct edit page behaviour when using generated pages. For example, if we have <code>edit_uri</code> set to <code>blob/master/docs/</code> and the following file structure:</p> <pre><code>repo/\n    mkdocs.yml\n    docs/\n        index.md\n    scripts/\n        gen_ref_pages.py\n    src/\n        project/\n            lorem.py\n            ipsum.py\n            dolor.py\n            sit.py\n            amet.py\n</code></pre> <p>Then we will have to change our <code>set_edit_path</code> call to:</p> <pre><code>mkdocs_gen_files.set_edit_path(full_doc_path, Path(\"../\") / path)  # (1)!\n</code></pre> <ol> <li>Path can be used to traverse the structure in any way you may need, but    remember to use relative paths!</li> </ol> <p>...so that it correctly sets the edit path of (for example) <code>lorem.py</code> to <code>&lt;repo_url&gt;/blob/master/src/project/lorem.py</code> instead of <code>&lt;repo_url&gt;/blob/master/docs/src/project/lorem.py</code>.</p> <p>With this script, a <code>reference</code> folder is automatically created each time we build our docs. This folder contains a Markdown page for each of our source modules, and each of these pages contains a single line of the form <code>project.module</code> (module being <code>lorem</code>, <code>ipsum</code>, etc.). Great! But, we still have to actually add those pages into our MkDocs navigation:</p> mkdocs.yml<pre><code>nav:\n# rest of the navigation...\n- Code Reference:\n  - project:\n    - lorem: reference/project/lorem.md\n    - ipsum: reference/project/ipsum.md\n    - dolor: reference/project/dolor.md\n    - sit: reference/project/sit.md\n    - amet: reference/project/amet.md\n# rest of the navigation...\n</code></pre> <p>Err... so this process is only semi-automatic? Yes, but don't worry, we can fully automate it.</p>","path":["Usage","Guides","Recipes"],"tags":[]},{"location":"recipes/#generate-a-literate-navigation-file","level":3,"title":"Generate a literate navigation file","text":"<p>mkdocs-gen-files is able to generate a literate navigation file. But to make use of it, we will need an additional plugin: mkdocs-literate-nav. This plugin allows to specify the whole navigation, or parts of it, into Markdown pages, as plain Markdown lists. We use it here to specify the navigation for the code reference pages.</p> <p>First, add <code>mkdocs-literate-nav</code> to your project's docs dependencies, and configure the plugin in your MkDocs configuration:</p> mkdocs.yml<pre><code>plugins:\n- search\n- gen-files:\n    scripts:\n    - scripts/gen_ref_pages.py\n- literate-nav:\n    nav_file: SUMMARY.md\n- mkdocstrings\n</code></pre> <p>Then, the previous script is updated like so:</p> scripts/gen_ref_pages.py<pre><code>\"\"\"Generate the code reference pages and navigation.\"\"\"\n\nfrom pathlib import Path\n\nimport mkdocs_gen_files\n\nnav = mkdocs_gen_files.Nav()\n\nroot = Path(__file__).parent.parent\nsrc = root / \"src\"\n\nfor path in sorted(src.rglob(\"*.py\")):\n    module_path = path.relative_to(src).with_suffix(\"\")\n    doc_path = path.relative_to(src).with_suffix(\".md\")\n    full_doc_path = Path(\"reference\", doc_path)\n\n    parts = tuple(module_path.parts)\n\n    if parts[-1] == \"__init__\":\n        parts = parts[:-1]\n    elif parts[-1] == \"__main__\":\n        continue\n\n    nav[parts] = doc_path.as_posix()  # (1)!\n\n    with mkdocs_gen_files.open(full_doc_path, \"w\") as fd:\n        ident = \".\".join(parts)\n        fd.write(f\"::: {ident}\")\n\n    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))\n\nwith mkdocs_gen_files.open(\"reference/SUMMARY.md\", \"w\") as nav_file:  # (2)!\n    nav_file.writelines(nav.build_literate_nav())  # (3)!\n</code></pre> <ol> <li>Progressively build the navigation object.</li> <li>At the end, create a magic, literate navigation file called <code>SUMMARY.md</code> in the <code>reference</code> folder.</li> <li>Write the navigation as a Markdown list in the literate navigation file.</li> </ol> <p>Now we are able to remove our hard-coded navigation in <code>mkdocs.yml</code>, and replace it with a single line!</p> mkdocs.yml<pre><code>nav:\n# rest of the navigation...\n# defer to gen-files + literate-nav\n- Code Reference: reference/  # (1)!\n# rest of the navigation...\n</code></pre> <ol> <li>Note the trailing slash! It is needed so that <code>mkdocs-literate-nav</code> knows    it has to look for a <code>SUMMARY.md</code> file in that folder.</li> </ol> <p>At this point, we should be able to see the tree of our modules in the navigation.</p>","path":["Usage","Guides","Recipes"],"tags":[]},{"location":"recipes/#bind-pages-to-sections-themselves","level":3,"title":"Bind pages to sections themselves","text":"<p>There's a last improvement we can do. With the current script, sections, corresponding to folders, will expand or collapse when you click on them, revealing <code>__init__</code> modules under them (or equivalent modules in other languages, if relevant). Since we are documenting a public API, and given users never explicitly import <code>__init__</code> modules, it would be nice if we could get rid of them and instead render their documentation inside the section itself.</p> <p>Well, this is possible thanks to a third plugin: mkdocs-section-index.</p> <p>Update the script like this:</p> scripts/gen_ref_pages.py<pre><code>\"\"\"Generate the code reference pages and navigation.\"\"\"\n\nfrom pathlib import Path\n\nimport mkdocs_gen_files\n\nnav = mkdocs_gen_files.Nav()\n\nroot = Path(__file__).parent.parent\nsrc = root / \"src\"\n\nfor path in sorted(src.rglob(\"*.py\")):\n    module_path = path.relative_to(src).with_suffix(\"\")\n    doc_path = path.relative_to(src).with_suffix(\".md\")\n    full_doc_path = Path(\"reference\", doc_path)\n\n    parts = tuple(module_path.parts)\n\n    if parts[-1] == \"__init__\":\n        parts = parts[:-1]\n        doc_path = doc_path.with_name(\"index.md\")\n        full_doc_path = full_doc_path.with_name(\"index.md\")\n    elif parts[-1] == \"__main__\":\n        continue\n\n    nav[parts] = doc_path.as_posix()\n\n    with mkdocs_gen_files.open(full_doc_path, \"w\") as fd:\n        ident = \".\".join(parts)\n        fd.write(f\"::: {ident}\")\n\n    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))\n\nwith mkdocs_gen_files.open(\"reference/SUMMARY.md\", \"w\") as nav_file:\n    nav_file.writelines(nav.build_literate_nav())\n</code></pre> <p>And update your MkDocs configuration to list the plugin:</p> mkdocs.yml<pre><code>plugins:\n- search\n- gen-files:\n    scripts:\n    - scripts/gen_ref_pages.py\n- literate-nav:\n    nav_file: SUMMARY.md\n- section-index\n- mkdocstrings\n</code></pre> <p>With this, <code>__init__</code> modules will be documented and bound to the sections themselves, better reflecting our public API.</p>","path":["Usage","Guides","Recipes"],"tags":[]},{"location":"recipes/#prevent-selection-of-prompts-and-output-in-python-code-blocks","level":2,"title":"Prevent selection of prompts and output in Python code blocks","text":"<p>To prevent the selection of <code>&gt;&gt;&gt;</code>, <code>...</code> and output in Python \"Console\" code blocks, you can use the <code>pycon</code> syntax highlighting on your code blocks, and add global CSS rules to your site using MkDocs <code>extra_css</code> option:</p> <pre><code>```pycon\n&gt;&gt;&gt; for word in (\"Hello\", \"mkdocstrings!\"):\n...     print(word, end=\" \")\n...\nHello mkdocstrings!\n```\n</code></pre> docs/css/code_select.css<pre><code>.highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */\n    user-select: none;\n}\n</code></pre> mkdocs.yml<pre><code>extra_css:\n- css/code_select.css\n</code></pre> <p>Warning</p> <p> The <code>.highlight .gp, .highlight .go</code> CSS selector can have unintended side-effects. To target <code>pycon</code> code blocks more specifically, you can configure the <code>pymdownx.highlight</code> extension to use Pygments and set language classes on code blocks:</p> mkdocs.yml<pre><code>markdown_extensions:\n- pymdownx.highlight:\n    use_pygments: true\n    pygments_lang_class: true\n</code></pre> <p>Then you can update the CSS selector like this:</p> docs/css/code_select.css<pre><code>.language-pycon .gp, .language-pycon .go { /* Generic.Prompt, Generic.Output */\n    user-select: none;\n}\n</code></pre> <p>If you don't want to enable this globally, you can still use <code>style</code> tags in the relevant pages, with more accurate CSS selectors:</p> <pre><code>&lt;style&gt;\n#my-div .highlight .gp, #my-div .highlight .go { /* Generic.Prompt, Generic.Output */\n    user-select: none;\n}\n&lt;/style&gt;\n</code></pre> <p>Try to select the following code block's text:</p> <pre><code>&gt;&gt;&gt; for word in (\"Hello\", \"mkdocstrings!\"):\n...     print(word, end=\" \")\nHello mkdocstrings!\n</code></pre>","path":["Usage","Guides","Recipes"],"tags":[]},{"location":"recipes/#hide-documentation-strings-from-source-code-blocks","level":2,"title":"Hide documentation strings from source code blocks","text":"<p>Since documentation strings are rendered by handlers, it can sometimes feel redundant to show these same documentation strings in source code blocks (when handlers render those).</p> <p>There is a general workaround to hide these docstrings from source blocks using CSS:</p> <pre><code>/* These CSS classes depend on the handler. */\n.doc-contents details .highlight code {\n  line-height: 0;\n}\n.doc-contents details .highlight code &gt; * {\n  line-height: initial;\n}\n.doc-contents details .highlight code &gt; .sd {  /* Literal.String.Doc */\n  display: none;\n}\n</code></pre> <p>Note that this is considered a workaround and not a proper solution, because it has side-effects like also removing blank lines.</p>","path":["Usage","Guides","Recipes"],"tags":[]},{"location":"recipes/#automatic-highlighting-for-indented-code-blocks-in-docstrings","level":2,"title":"Automatic highlighting for indented code blocks in docstrings","text":"<p>Depending on the language used in your code base and the mkdocstrings handler used to document it, you might want to set a default syntax for code blocks added to your docstrings. For example, to default to the Python syntax:</p> mkdocs.yml<pre><code>markdown_extensions:\n- pymdownx.highlight:\n    default_lang: python\n</code></pre> <p>Then in your docstrings, indented code blocks will be highlighted as Python code:</p> <pre><code>def my_function():\n    \"\"\"This is my function.\n\n    The following code will be highlighted as Python:\n\n        result = my_function()\n        print(result)\n\n    End of the docstring.\n    \"\"\"\n    pass\n</code></pre>","path":["Usage","Guides","Recipes"],"tags":[]},{"location":"troubleshooting/","level":1,"title":"Troubleshooting","text":"","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#code-blocks-in-admonitions-in-docstrings-or-else-are-not-rendered-correctly","level":2,"title":"Code blocks in admonitions (in docstrings or else) are not rendered correctly","text":"<p>To render code blocks in admonitions, you need to add the <code>pymdownx.superfences</code> extensions to the list of Markdown extensions in <code>mkdocs.yml</code>. For example:</p> <pre><code>!!! note\n    Some text.\n\n    ```bash\n    echo \"some code\"\n    ```\n</code></pre> mkdocs.yml<pre><code>markdown_extensions:\n- admonition\n- codehilite\n- pymdownx.superfences\n</code></pre> <p>For code blocks in docstrings, make sure to escape newlines (<code>\\n</code> -&gt; <code>\\\\n</code>), or prefix the entire docstring with 'r' to make it a raw-docstring: <code>r\"\"\"</code>. Indeed, docstrings are still strings and therefore subject to how Python parses strings.</p>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#footnotes-are-duplicated-or-overridden","level":2,"title":"Footnotes are duplicated or overridden","text":"<p>Before version 0.14, footnotes could be duplicated over a page. Please upgrade to version 0.14 or higher.</p> <p>See also:</p> <ul> <li>Issue #186</li> <li>Tabs in docstrings (from <code>pymdownx.tabbed</code>) are not working properly.</li> </ul>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#mkdocs-warns-me-about-links-to-unfound-documentation-files","level":2,"title":"MkDocs warns me about links to unfound documentation files","text":"<p>A warning like this one:</p> <p>WARNING -  Documentation file 'reference/parsers/docstrings.md'   contains a link to 'reference/parsers/pytkdocs.parsers.docstrings.Section'   which is not found in the documentation files.</p> <p>...generally means you used parentheses <code>()</code> instead of brackets <code>[]</code> for a cross-reference. Notice the dots in <code>reference/parsers/pytkdocs.parsers.docstrings.Section</code>? It shows that it's probably a cross-reference, not a direct link. It's probably written like <code>[Section](pytkdocs.parsers.docstrings.Section)</code> in the docs, when it should be <code>[Section][pytkdocs.parsers.docstrings.Section]</code>.</p>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#some-objects-are-not-rendered-they-do-not-appear-in-the-generated-docs","level":2,"title":"Some objects are not rendered (they do not appear in the generated docs)","text":"<ul> <li>Make sure the configuration options of the handler are correct.   Check the documentation for Handlers to see the available options for each handler.</li> <li>Also make sure your documentation in your source code is formatted correctly.   For Python code, check the supported docstring styles page.</li> <li>Re-run the Mkdocs command with <code>-v</code>, and carefully read any traceback.</li> </ul>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#tabs-in-docstrings-from-pymdownxtabbed-are-not-working-properly","level":2,"title":"Tabs in docstrings (from <code>pymdownx.tabbed</code>) are not working properly","text":"<p>Before version 0.14, multiple tab blocks injected on the same page would result in broken links: clicking on a tab would bring the user to the wrong one. Please upgrade to version 0.14 or higher.</p> <p>See also:</p> <ul> <li>Issue #193</li> <li>Footnotes are duplicated or overridden.</li> </ul> <p>If you are stuck on a version before 0.14, and want to use multiple tab blocks in one page, use this workaround.</p> JavaScript workaround <p>Put the following code in a .js file, and list it in MkDocs' <code>extra_javascript</code>:</p> <pre><code>// Credits to Nikolaos Zioulis (@zuru on GitHub)\nfunction setID(){\n    var tabs = document.getElementsByClassName(\"tabbed-set\");\n    for (var i = 0; i &lt; tabs.length; i++) {\n        children = tabs[i].children;\n        var counter = 0;\n        var iscontent = 0;\n        for(var j = 0; j &lt; children.length;j++){\n            if(typeof children[j].htmlFor === 'undefined'){\n                if((iscontent + 1) % 2 == 0){\n                    // check if it is content\n                    if(iscontent == 1){\n                        btn = children[j].childNodes[1].getElementsByTagName(\"button\");\n                    }\n                }\n                else{\n                    // if not change the id\n                    children[j].id = \"__tabbed_\" + String(i + 1) + \"_\" + String(counter + 1);\n                    children[j].name = \"__tabbed_\" + String(i + 1);\n                    // make default tab open\n                    if(j == 0)\n                        children[j].click();\n                }\n                iscontent++;\n            }\n            else{\n                // link to the correct tab\n                children[j].htmlFor = \"__tabbed_\" + String(i+1) + \"_\" + String(counter + 1);\n                counter ++;\n            }\n        }\n    }\n}\nsetID();\n</code></pre> <p>This code will correctly reset the IDs for tabs on a same page.</p>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#the-generated-documentation-does-not-look-good","level":2,"title":"The generated documentation does not look good","text":"<p>Please open an ticket on the bugtracker with a detailed explanation and screenshots of the bad-looking parts. Note that you can always customize the look of mkdocstrings blocks -- through both HTML and CSS.</p>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#warning-could-not-find-cross-reference-target","level":2,"title":"Warning: could not find cross-reference target","text":"<p>New in version 0.15</p> <p>Cross-linking used to include any Markdown heading, but now it's only for mkdocstrings identifiers by default. See Cross-references to any Markdown heading to opt back in.</p> <p>Make sure the referenced object is properly rendered: verify your configuration options.</p> <p>For false-positives, you can wrap the text in backticks (`) to prevent <code>mkdocstrings</code> from trying to process it.</p>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#python-specifics","level":2,"title":"Python specifics","text":"","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#nothing-is-rendered-at-all","level":3,"title":"Nothing is rendered at all","text":"<p>Is your package available in the Python path?</p> <p>See Python handler: Finding modules.</p>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#latex-in-docstrings-is-not-rendered-correctly","level":3,"title":"LaTeX in docstrings is not rendered correctly","text":"<p>If you are using a Markdown extension like Arithmatex Mathjax or <code>markdown-katex</code> to render LaTeX, add <code>r</code> in front of your docstring to make sure nothing is escaped. You'll still maybe have to play with escaping to get things right.</p> <p>Example:</p> <pre><code>def math_function(x, y):\n    r\"\"\"\n    Look at these formulas:\n\n    ```math\n    f(x) = \\int_{-\\infty}^\\infty\n    \\hat f(\\xi)\\,e^{2 \\pi i \\xi x}\n    \\,d\\xi\n    ```\n    \"\"\"\n</code></pre>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#my-docstrings-in-comments-are-not-picked-up","level":3,"title":"My docstrings in comments (<code>#:</code>) are not picked up","text":"<p>We only support docstrings in comments through the griffe-sphinx extension.</p> <p>Alternatively, instead of:</p> <pre><code>import enum\n\n\nclass MyEnum(enum.Enum):\n    v1 = 1  #: The first choice.\n    v2 = 2  #: The second choice.\n</code></pre> <p>You can use:</p> <pre><code>import enum\n\n\nclass MyEnum(enum.Enum):\n    v1 = 1\n    \"\"\"The first choice.\"\"\"\n\n    v2 = 2\n    \"\"\"The second choice.\"\"\"\n</code></pre> <p>Or:</p> <pre><code>import enum\n\n\nclass MyEnum(enum.Enum):\n    \"\"\"My enum.\n\n    Attributes:\n        v1: The first choice.\n        v2: The second choice.\n    \"\"\"\n\n    v1 = 1\n    v2 = 2\n</code></pre>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#my-wrapped-function-shows-documentationcode-for-its-wrapper-instead-of-its-own","level":3,"title":"My wrapped function shows documentation/code for its wrapper instead of its own","text":"<p>Use <code>functools.wraps()</code>:</p> <pre><code>from functools import wraps\n\n\ndef my_decorator(function):\n    \"\"\"The decorator docs.\"\"\"\n\n    @wraps(function)\n    def wrapped_function(*args, **kwargs):\n        print(\"hello\")\n        function(*args, **kwargs)\n        print(\"bye\")\n\n    return wrapped_function\n\n\n@my_decorator\ndef my_function(*args, **kwargs):\n    \"\"\"The function docs.\"\"\"\n    print(*args, **kwargs)\n</code></pre>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#footnotes-do-not-render","level":3,"title":"Footnotes do not render","text":"<p>The library that parses docstrings, Griffe, splits docstrings in several \"sections\" (example: Google-style sections syntax). If a footnote is used in a section, while referenced in another, mkdocstrings won't be able to render it correctly. The footnote and its reference must appear in the same section.</p> <pre><code>def my_function():\n    \"\"\"Summary.\n\n    This is the first section[^1].\n\n    Note:\n        This is the second section[^2].\n\n    Note:\n        This is the third section[^3].\n\n    References at the end are part of yet another section (fourth here)[^4].\n\n    [^1]: Some text.\n    [^2]: Some text.\n    [^3]: Some text.\n    [^4]: Some text.\n    \"\"\"\n</code></pre> <p>Here only the fourth footnote will work, because it is the only one that appear in the same section as its reference. To fix this, make sure all footnotes appear in the same section as their references:</p> <pre><code>def my_function():\n    \"\"\"Summary.\n\n    This is the first section[^1].\n\n    [^1]: Some text.\n\n    Note:\n        This is the second section[^2].\n\n        [^2]: Some text.\n\n    Note:\n        This is the third section[^3].\n\n        [^3]: Some text.\n\n    References at the end are part of yet another section (fourth here)[^4].\n\n    [^4]: Some text.\n    \"\"\"\n</code></pre>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"troubleshooting/#submodules-are-not-rendered","level":3,"title":"Submodules are not rendered","text":"<p>In previous versions of mkdocstrings-python, submodules were rendered by default. This was changed and you now need to set the following option:</p> mkdocs.yml<pre><code>plugins:\n- mkdocstrings:\n    handlers:\n      python:\n        options:\n          show_submodules: true\n</code></pre>","path":["Usage","Guides","Troubleshooting"],"tags":[]},{"location":"reference/api/","level":1,"title":"API reference","text":"","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings","level":1,"title":"mkdocstrings","text":"<p>mkdocstrings package.</p> <p>Automatic documentation from sources, for MkDocs.</p> <p>Classes:</p> <ul> <li> <code>AutoDocProcessor</code>           –            <p>Our \"autodoc\" Markdown block processor.</p> </li> <li> <code>BaseHandler</code>           –            <p>The base handler class.</p> </li> <li> <code>CollectionError</code>           –            <p>An exception raised when some collection of data failed.</p> </li> <li> <code>Handlers</code>           –            <p>A collection of handlers.</p> </li> <li> <code>HeadingShiftingTreeprocessor</code>           –            <p>Shift levels of all Markdown headings according to the configured base level.</p> </li> <li> <code>Highlighter</code>           –            <p>Code highlighter that tries to match the Markdown configuration.</p> </li> <li> <code>IdPrependingTreeprocessor</code>           –            <p>Prepend the configured prefix to IDs of all HTML elements.</p> </li> <li> <code>Inventory</code>           –            <p>Inventory of collected and rendered objects.</p> </li> <li> <code>InventoryItem</code>           –            <p>Inventory item.</p> </li> <li> <code>LoggerAdapter</code>           –            <p>A logger adapter to prefix messages.</p> </li> <li> <code>MkdocstringsExtension</code>           –            <p>Our Markdown extension.</p> </li> <li> <code>MkdocstringsInnerExtension</code>           –            <p>Extension that should always be added to Markdown sub-documents that handlers request (and only them).</p> </li> <li> <code>MkdocstringsPlugin</code>           –            <p>An <code>mkdocs</code> plugin.</p> </li> <li> <code>ParagraphStrippingTreeprocessor</code>           –            <p>Unwraps the <code>&lt;p&gt;</code> element around the whole output.</p> </li> <li> <code>PluginConfig</code>           –            <p>The configuration options of <code>mkdocstrings</code>, written in <code>mkdocs.yml</code>.</p> </li> <li> <code>TemplateLogger</code>           –            <p>A wrapper class to allow logging in templates.</p> </li> <li> <code>ThemeNotSupported</code>           –            <p>An exception raised to tell a theme is not supported.</p> </li> </ul> <p>Functions:</p> <ul> <li> <code>do_any</code>             –              <p>Check if at least one of the item in the sequence evaluates to true.</p> </li> <li> <code>get_logger</code>             –              <p>Return a pre-configured logger.</p> </li> <li> <code>get_template_logger</code>             –              <p>Return a logger usable in templates.</p> </li> <li> <code>get_template_logger_function</code>             –              <p>Create a wrapper function that automatically receives the Jinja template context.</p> </li> <li> <code>get_template_path</code>             –              <p>Return the path to the template currently using the given context.</p> </li> <li> <code>makeExtension</code>             –              <p>Create the extension instance.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>CollectorItem</code>           –            <p>The type of the item returned by the <code>collect</code> method of a handler.</p> </li> <li> <code>HandlerConfig</code>           –            <p>The type of the configuration of a handler.</p> </li> <li> <code>HandlerOptions</code>           –            <p>The type of the options passed to a handler.</p> </li> <li> <code>TEMPLATES_DIRS</code>               (<code>Sequence[Path]</code>)           –            <p>The directories where the handler templates are located.</p> </li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.CollectorItem","level":2,"title":"CollectorItem  <code>module-attribute</code>","text":"<pre><code>CollectorItem = Any\n</code></pre> <p>The type of the item returned by the <code>collect</code> method of a handler.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HandlerConfig","level":2,"title":"HandlerConfig  <code>module-attribute</code>","text":"<pre><code>HandlerConfig = Any\n</code></pre> <p>The type of the configuration of a handler.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HandlerOptions","level":2,"title":"HandlerOptions  <code>module-attribute</code>","text":"<pre><code>HandlerOptions = Any\n</code></pre> <p>The type of the options passed to a handler.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.TEMPLATES_DIRS","level":2,"title":"TEMPLATES_DIRS  <code>module-attribute</code>","text":"<pre><code>TEMPLATES_DIRS: Sequence[Path] = tuple(__path__)\n</code></pre> <p>The directories where the handler templates are located.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor","level":2,"title":"AutoDocProcessor","text":"<pre><code>AutoDocProcessor(\n    md: Markdown,\n    *,\n    handlers: Handlers,\n    autorefs: AutorefsPlugin,\n)\n</code></pre> <p>               Bases: <code>BlockProcessor</code></p> <p>Our \"autodoc\" Markdown block processor.</p> <p>It has a <code>test</code> method that tells if a block matches a criterion, and a <code>run</code> method that processes it.</p> <p>It also has utility methods allowing to get handlers and their configuration easily, useful when processing a matched block.</p> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>run</code>             –              <p>Run code on the matched blocks.</p> </li> <li> <code>test</code>             –              <p>Match our autodoc instructions.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>md</code>           –            <p>The Markdown instance.</p> </li> <li> <code>regex</code>           –            <p>The regular expression to match our autodoc instructions.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/extension.py</code> <pre><code>def __init__(\n    self,\n    md: Markdown,\n    *,\n    handlers: Handlers,\n    autorefs: AutorefsPlugin,\n) -&gt; None:\n    \"\"\"Initialize the object.\n\n    Arguments:\n        md: A `markdown.Markdown` instance.\n        handlers: The handlers container.\n        autorefs: The autorefs plugin instance.\n    \"\"\"\n    super().__init__(parser=md.parser)\n    self.md = md\n    \"\"\"The Markdown instance.\"\"\"\n    self._handlers = handlers\n    self._autorefs = autorefs\n    self._updated_envs: set = set()\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor(md)","level":3,"title":"<code>md</code>","text":"(<code>Markdown</code>)           –            <p>A <code>markdown.Markdown</code> instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor(handlers)","level":3,"title":"<code>handlers</code>","text":"(<code>Handlers</code>)           –            <p>The handlers container.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor(autorefs)","level":3,"title":"<code>autorefs</code>","text":"(<code>AutorefsPlugin</code>)           –            <p>The autorefs plugin instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor.md","level":3,"title":"md  <code>instance-attribute</code>","text":"<pre><code>md = md\n</code></pre> <p>The Markdown instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor.regex","level":3,"title":"regex  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>regex = compile(\n    \"^(?P&lt;heading&gt;#{1,6} *|)::: ?(?P&lt;name&gt;.+?) *$\",\n    flags=MULTILINE,\n)\n</code></pre> <p>The regular expression to match our autodoc instructions.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor.run","level":3,"title":"run","text":"<pre><code>run(parent: Element, blocks: MutableSequence[str]) -&gt; None\n</code></pre> <p>Run code on the matched blocks.</p> <p>The identifier and configuration lines are retrieved from a matched block and used to collect and render an object.</p> <p>Parameters:</p> Source code in <code>src/mkdocstrings/_internal/extension.py</code> <pre><code>def run(self, parent: Element, blocks: MutableSequence[str]) -&gt; None:\n    \"\"\"Run code on the matched blocks.\n\n    The identifier and configuration lines are retrieved from a matched block\n    and used to collect and render an object.\n\n    Arguments:\n        parent: The parent element in the XML tree.\n        blocks: The rest of the blocks to be processed.\n    \"\"\"\n    block = blocks.pop(0)\n    match = self.regex.search(block)\n\n    if match:\n        if match.start() &gt; 0:\n            self.parser.parseBlocks(parent, [block[: match.start()]])\n        # removes the first line\n        block = block[match.end() :]\n\n    block, the_rest = self.detab(block)\n\n    if not block and blocks and blocks[0].startswith((\"    handler:\", \"    options:\")):\n        # YAML options were separated from the `:::` line by a blank line.\n        block = blocks.pop(0)\n\n    if match:\n        identifier = match[\"name\"]\n        heading_level = match[\"heading\"].count(\"#\")\n        _logger.debug(\"Matched '::: %s'\", identifier)\n\n        html, handler, _ = self._process_block(identifier, block, heading_level)\n        el = Element(\"div\", {\"class\": \"mkdocstrings\"})\n        # The final HTML is inserted as opaque to subsequent processing, and only revealed at the end.\n        el.text = self.md.htmlStash.store(html)\n\n        if handler.outer_layer:\n            self._process_headings(handler, el)\n\n        parent.append(el)\n\n    if the_rest:\n        # This block contained unindented line(s) after the first indented\n        # line. Insert these lines as the first block of the master blocks\n        # list for future processing.\n        blocks.insert(0, the_rest)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor.run(parent)","level":4,"title":"<code>parent</code>","text":"(<code>Element</code>)           –            <p>The parent element in the XML tree.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor.run(blocks)","level":4,"title":"<code>blocks</code>","text":"(<code>MutableSequence[str]</code>)           –            <p>The rest of the blocks to be processed.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor.test","level":3,"title":"test","text":"<pre><code>test(parent: Element, block: str) -&gt; bool\n</code></pre> <p>Match our autodoc instructions.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>bool</code>           –            <p>Whether this block should be processed or not.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/extension.py</code> <pre><code>def test(self, parent: Element, block: str) -&gt; bool:  # noqa: ARG002\n    \"\"\"Match our autodoc instructions.\n\n    Arguments:\n        parent: The parent element in the XML tree.\n        block: The block to be tested.\n\n    Returns:\n        Whether this block should be processed or not.\n    \"\"\"\n    return bool(self.regex.search(block))\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor.test(parent)","level":4,"title":"<code>parent</code>","text":"(<code>Element</code>)           –            <p>The parent element in the XML tree.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.AutoDocProcessor.test(block)","level":4,"title":"<code>block</code>","text":"(<code>str</code>)           –            <p>The block to be tested.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler","level":2,"title":"BaseHandler","text":"<pre><code>BaseHandler(\n    *,\n    theme: str,\n    custom_templates: str | None,\n    mdx: Sequence[str | Extension],\n    mdx_config: Mapping[str, Any],\n)\n</code></pre> <p>The base handler class.</p> <p>Inherit from this class to implement a handler.</p> <p>You will have to implement the <code>collect</code> and <code>render</code> methods. You can also implement the <code>teardown</code> method, and  override the <code>update_env</code> method, to add more filters to the Jinja environment, making them available in your Jinja templates.</p> <p>To define a fallback theme, add a <code>fallback_theme</code> class-variable. To add custom CSS, add an <code>extra_css</code> variable or create an 'style.css' file beside the templates.</p> <p>If the given theme is not supported (it does not exist), it will look for a <code>fallback_theme</code> attribute in <code>self</code> to use as a fallback theme.</p> <p>Other Parameters:</p> <ul> <li> <code>theme</code>               (<code>str</code>)           –            <p>The theme to use.</p> </li> <li> <code>custom_templates</code>               (<code>str | None</code>)           –            <p>The path to custom templates.</p> </li> <li> <code>mdx</code>               (<code>list[str | Extension]</code>)           –            <p>A list of Markdown extensions to use.</p> </li> <li> <code>mdx_config</code>               (<code>Mapping[str, Mapping[str, Any]]</code>)           –            <p>Configuration for the Markdown extensions.</p> </li> </ul> <p>Methods:</p> <ul> <li> <code>collect</code>             –              <p>Collect data given an identifier and user configuration.</p> </li> <li> <code>do_convert_markdown</code>             –              <p>Render Markdown text; for use inside templates.</p> </li> <li> <code>do_heading</code>             –              <p>Render an HTML heading and register it for the table of contents. For use inside templates.</p> </li> <li> <code>get_aliases</code>             –              <p>Return the possible aliases for a given identifier.</p> </li> <li> <code>get_extended_templates_dirs</code>             –              <p>Load template extensions for the given handler, return their templates directories.</p> </li> <li> <code>get_headings</code>             –              <p>Return and clear the headings gathered so far.</p> </li> <li> <code>get_inventory_urls</code>             –              <p>Return the URLs (and configuration options) of the inventory files to download.</p> </li> <li> <code>get_options</code>             –              <p>Get combined options.</p> </li> <li> <code>get_templates_dir</code>             –              <p>Return the path to the handler's templates directory.</p> </li> <li> <code>load_inventory</code>             –              <p>Yield items and their URLs from an inventory file streamed from <code>in_file</code>.</p> </li> <li> <code>render</code>             –              <p>Render a template using provided data and configuration options.</p> </li> <li> <code>render_backlinks</code>             –              <p>Render backlinks.</p> </li> <li> <code>teardown</code>             –              <p>Teardown the handler.</p> </li> <li> <code>update_env</code>             –              <p>Update the Jinja environment.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>custom_templates</code>           –            <p>The path to custom templates.</p> </li> <li> <code>domain</code>               (<code>str</code>)           –            <p>The handler's domain, used to register objects in the inventory, for example \"py\".</p> </li> <li> <code>enable_inventory</code>               (<code>bool</code>)           –            <p>Whether the inventory creation is enabled.</p> </li> <li> <code>env</code>           –            <p>The Jinja environment.</p> </li> <li> <code>extra_css</code>               (<code>str</code>)           –            <p>Extra CSS.</p> </li> <li> <code>fallback_theme</code>               (<code>str</code>)           –            <p>Fallback theme to use when a template isn't found in the configured theme.</p> </li> <li> <code>md</code>               (<code>Markdown</code>)           –            <p>The Markdown instance.</p> </li> <li> <code>mdx</code>           –            <p>The Markdown extensions to use.</p> </li> <li> <code>mdx_config</code>           –            <p>The configuration for the Markdown extensions.</p> </li> <li> <code>name</code>               (<code>str</code>)           –            <p>The handler's name, for example \"python\".</p> </li> <li> <code>outer_layer</code>               (<code>bool</code>)           –            <p>Whether we're in the outer Markdown conversion layer.</p> </li> <li> <code>theme</code>           –            <p>The selected theme.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def __init__(\n    self,\n    *,\n    theme: str,\n    custom_templates: str | None,\n    mdx: Sequence[str | Extension],\n    mdx_config: Mapping[str, Any],\n) -&gt; None:\n    \"\"\"Initialize the object.\n\n    If the given theme is not supported (it does not exist), it will look for a `fallback_theme` attribute\n    in `self` to use as a fallback theme.\n\n    Keyword Arguments:\n        theme (str): The theme to use.\n        custom_templates (str | None): The path to custom templates.\n        mdx (list[str | Extension]): A list of Markdown extensions to use.\n        mdx_config (Mapping[str, Mapping[str, Any]]): Configuration for the Markdown extensions.\n    \"\"\"\n    self.theme = theme\n    \"\"\"The selected theme.\"\"\"\n    self.custom_templates = custom_templates\n    \"\"\"The path to custom templates.\"\"\"\n    self.mdx = mdx\n    \"\"\"The Markdown extensions to use.\"\"\"\n    self.mdx_config = mdx_config\n    \"\"\"The configuration for the Markdown extensions.\"\"\"\n    self._md: Markdown | None = None\n    self._headings: list[Element] = []\n\n    paths = []\n\n    # add selected theme templates\n    themes_dir = self.get_templates_dir(self.name)\n    paths.append(themes_dir / self.theme)\n\n    # add extended theme templates\n    extended_templates_dirs = self.get_extended_templates_dirs(self.name)\n    paths.extend(templates_dir / self.theme for templates_dir in extended_templates_dirs)\n\n    # add fallback theme templates\n    if self.fallback_theme and self.fallback_theme != self.theme:\n        paths.append(themes_dir / self.fallback_theme)\n\n        # add fallback theme of extended templates\n        paths.extend(templates_dir / self.fallback_theme for templates_dir in extended_templates_dirs)\n\n    for path in paths:\n        css_path = path / \"style.css\"\n        if css_path.is_file():\n            self.extra_css += \"\\n\" + css_path.read_text(encoding=\"utf-8\")\n            break\n\n    if self.custom_templates is not None:\n        paths.insert(0, Path(self.custom_templates) / self.name / self.theme)\n\n    self.env = Environment(\n        autoescape=True,\n        loader=FileSystemLoader(paths),\n        auto_reload=False,  # Editing a template in the middle of a build is not useful.\n    )\n    \"\"\"The Jinja environment.\"\"\"\n\n    self.env.filters[\"convert_markdown\"] = self.do_convert_markdown\n    self.env.filters[\"heading\"] = self.do_heading\n    self.env.filters[\"any\"] = do_any\n    self.env.globals[\"log\"] = get_template_logger(self.name)  # ty:ignore[invalid-assignment]\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.custom_templates","level":3,"title":"custom_templates  <code>instance-attribute</code>","text":"<pre><code>custom_templates = custom_templates\n</code></pre> <p>The path to custom templates.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.domain","level":3,"title":"domain  <code>class-attribute</code>","text":"<pre><code>domain: str\n</code></pre> <p>The handler's domain, used to register objects in the inventory, for example \"py\".</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.enable_inventory","level":3,"title":"enable_inventory  <code>class-attribute</code>","text":"<pre><code>enable_inventory: bool = False\n</code></pre> <p>Whether the inventory creation is enabled.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.env","level":3,"title":"env  <code>instance-attribute</code>","text":"<pre><code>env = Environment(\n    autoescape=True,\n    loader=FileSystemLoader(paths),\n    auto_reload=False,\n)\n</code></pre> <p>The Jinja environment.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.extra_css","level":3,"title":"extra_css  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>extra_css: str = ''\n</code></pre> <p>Extra CSS.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.fallback_theme","level":3,"title":"fallback_theme  <code>class-attribute</code>","text":"<pre><code>fallback_theme: str = ''\n</code></pre> <p>Fallback theme to use when a template isn't found in the configured theme.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.md","level":3,"title":"md  <code>property</code>","text":"<pre><code>md: Markdown\n</code></pre> <p>The Markdown instance.</p> <p>Raises:</p> <ul> <li> <code>RuntimeError</code>             –            <p>When the Markdown instance is not set yet.</p> </li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.mdx","level":3,"title":"mdx  <code>instance-attribute</code>","text":"<pre><code>mdx = mdx\n</code></pre> <p>The Markdown extensions to use.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.mdx_config","level":3,"title":"mdx_config  <code>instance-attribute</code>","text":"<pre><code>mdx_config = mdx_config\n</code></pre> <p>The configuration for the Markdown extensions.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.name","level":3,"title":"name  <code>class-attribute</code>","text":"<pre><code>name: str\n</code></pre> <p>The handler's name, for example \"python\".</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.outer_layer","level":3,"title":"outer_layer  <code>property</code>","text":"<pre><code>outer_layer: bool\n</code></pre> <p>Whether we're in the outer Markdown conversion layer.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.theme","level":3,"title":"theme  <code>instance-attribute</code>","text":"<pre><code>theme = theme\n</code></pre> <p>The selected theme.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.collect","level":3,"title":"collect","text":"<pre><code>collect(\n    identifier: str, options: HandlerOptions\n) -&gt; CollectorItem\n</code></pre> <p>Collect data given an identifier and user configuration.</p> <p>In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into a Python dictionary for example, though the implementation is completely free.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>CollectorItem</code>           –            <p>Anything you want, as long as you can feed it to the handler's <code>render</code> method.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def collect(self, identifier: str, options: HandlerOptions) -&gt; CollectorItem:\n    \"\"\"Collect data given an identifier and user configuration.\n\n    In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into\n    a Python dictionary for example, though the implementation is completely free.\n\n    Arguments:\n        identifier: An identifier for which to collect data. For example, in Python,\n            it would be 'mkdocstrings.BaseHandler' to collect documentation about the BaseHandler class.\n            It can be anything that you can feed to the tool of your choice.\n        options: The final configuration options.\n\n    Returns:\n        Anything you want, as long as you can feed it to the handler's `render` method.\n    \"\"\"\n    raise NotImplementedError\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.collect(identifier)","level":4,"title":"<code>identifier</code>","text":"(<code>str</code>)           –            <p>An identifier for which to collect data. For example, in Python, it would be 'mkdocstrings.BaseHandler' to collect documentation about the BaseHandler class. It can be anything that you can feed to the tool of your choice.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.collect(options)","level":4,"title":"<code>options</code>","text":"(<code>HandlerOptions</code>)           –            <p>The final configuration options.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_convert_markdown","level":3,"title":"do_convert_markdown","text":"<pre><code>do_convert_markdown(\n    text: str,\n    heading_level: int,\n    html_id: str = \"\",\n    *,\n    strip_paragraph: bool = False,\n    autoref_hook: AutorefsHookInterface | None = None,\n) -&gt; Markup\n</code></pre> <p>Render Markdown text; for use inside templates.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>Markup</code>           –            <p>An HTML string.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def do_convert_markdown(\n    self,\n    text: str,\n    heading_level: int,\n    html_id: str = \"\",\n    *,\n    strip_paragraph: bool = False,\n    autoref_hook: AutorefsHookInterface | None = None,\n) -&gt; Markup:\n    \"\"\"Render Markdown text; for use inside templates.\n\n    Arguments:\n        text: The text to convert.\n        heading_level: The base heading level to start all Markdown headings from.\n        html_id: The HTML id of the element that's considered the parent of this element.\n        strip_paragraph: Whether to exclude the `&lt;p&gt;` tag from around the whole output.\n\n    Returns:\n        An HTML string.\n    \"\"\"\n    global _markdown_conversion_layer  # noqa: PLW0603\n    _markdown_conversion_layer += 1\n    treeprocessors = self.md.treeprocessors\n    treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level\n    treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + \"--\"\n    treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph\n    if BacklinksTreeProcessor.name in treeprocessors:\n        treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id\n    if autoref_hook and AutorefsInlineProcessor.name in self.md.inlinePatterns:\n        self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook  # ty: ignore[unresolved-attribute]\n\n    try:\n        return Markup(self.md.convert(text))\n    finally:\n        treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0\n        treeprocessors[IdPrependingTreeprocessor.name].id_prefix = \"\"\n        treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False\n        if BacklinksTreeProcessor.name in treeprocessors:\n            treeprocessors[BacklinksTreeProcessor.name].initial_id = None\n        if AutorefsInlineProcessor.name in self.md.inlinePatterns:\n            self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = None\n        self.md.reset()\n        _markdown_conversion_layer -= 1\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_convert_markdown(text)","level":4,"title":"<code>text</code>","text":"(<code>str</code>)           –            <p>The text to convert.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_convert_markdown(heading_level)","level":4,"title":"<code>heading_level</code>","text":"(<code>int</code>)           –            <p>The base heading level to start all Markdown headings from.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_convert_markdown(html_id)","level":4,"title":"<code>html_id</code>","text":"(<code>str</code>, default:                   <code>''</code> )           –            <p>The HTML id of the element that's considered the parent of this element.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_convert_markdown(strip_paragraph)","level":4,"title":"<code>strip_paragraph</code>","text":"(<code>bool</code>, default:                   <code>False</code> )           –            <p>Whether to exclude the <code>&lt;p&gt;</code> tag from around the whole output.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_heading","level":3,"title":"do_heading","text":"<pre><code>do_heading(\n    content: Markup,\n    heading_level: int,\n    *,\n    role: str | None = None,\n    hidden: bool = False,\n    toc_label: str | None = None,\n    skip_inventory: bool = False,\n    **attributes: str,\n) -&gt; Markup\n</code></pre> <p>Render an HTML heading and register it for the table of contents. For use inside templates.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>Markup</code>           –            <p>An HTML string.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def do_heading(\n    self,\n    content: Markup,\n    heading_level: int,\n    *,\n    role: str | None = None,\n    hidden: bool = False,\n    toc_label: str | None = None,\n    skip_inventory: bool = False,\n    **attributes: str,\n) -&gt; Markup:\n    \"\"\"Render an HTML heading and register it for the table of contents. For use inside templates.\n\n    Arguments:\n        content: The HTML within the heading.\n        heading_level: The level of heading (e.g. 3 -&gt; `h3`).\n        role: An optional role for the object bound to this heading.\n        hidden: If True, only register it for the table of contents, don't render anything.\n        toc_label: The title to use in the table of contents ('data-toc-label' attribute).\n        skip_inventory: Flag element to not be registered in the inventory (by setting a `data-skip-inventory` attribute).\n        **attributes: Any extra HTML attributes of the heading.\n\n    Returns:\n        An HTML string.\n    \"\"\"\n    # Produce a heading element that will be used later, in `AutoDocProcessor.run`, to:\n    # - register it in the ToC: right now we're in the inner Markdown conversion layer,\n    #   so we have to bubble up the information to the outer Markdown conversion layer,\n    #   for the ToC extension to pick it up.\n    # - register it in autorefs: right now we don't know what page is being rendered,\n    #   so we bubble up the information again to where autorefs knows the page,\n    #   and can correctly register the heading anchor (id) to its full URL.\n    # - register it in the objects inventory: same as for autorefs,\n    #   we don't know the page here, or the handler (and its domain),\n    #   so we bubble up the information to where the mkdocstrings extension knows that.\n    el = Element(f\"h{heading_level}\", attributes)\n    if toc_label is None:\n        toc_label = content.unescape() if isinstance(content, Markup) else content\n    el.set(\"data-toc-label\", toc_label)\n    if skip_inventory:\n        el.set(\"data-skip-inventory\", \"true\")\n    if role:\n        el.set(\"data-role\", role)\n    if content:\n        el.text = str(content).strip()\n    self._headings.append(el)\n\n    if hidden:\n        return Markup('&lt;a id=\"{0}\"&gt;&lt;/a&gt;').format(attributes[\"id\"])\n\n    # Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.\n    # Start with a heading that has just attributes (no text), and add a placeholder into it.\n    el = Element(f\"h{heading_level}\", attributes)\n    el.append(Element(\"mkdocstrings-placeholder\"))\n    # Tell the inner 'toc' extension to make its additions if configured so.\n    toc = cast(\"TocTreeprocessor\", self.md.treeprocessors[\"toc\"])\n    if toc.use_anchors:\n        toc.add_anchor(el, attributes[\"id\"])\n    if toc.use_permalinks:\n        toc.add_permalink(el, attributes[\"id\"])\n\n    # The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle\n    # of the heading with a placeholder that can never occur (text can't directly contain angle brackets).\n    # Now this HTML wrapper can be \"filled\" by replacing the placeholder.\n    html_with_placeholder = tostring(el, encoding=\"unicode\")\n    assert (  # noqa: S101\n        html_with_placeholder.count(\"&lt;mkdocstrings-placeholder /&gt;\") == 1\n    ), f\"Bug in mkdocstrings: failed to replace in {html_with_placeholder!r}\"\n    html = html_with_placeholder.replace(\"&lt;mkdocstrings-placeholder /&gt;\", content)\n    return Markup(html)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_heading(content)","level":4,"title":"<code>content</code>","text":"(<code>Markup</code>)           –            <p>The HTML within the heading.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_heading(heading_level)","level":4,"title":"<code>heading_level</code>","text":"(<code>int</code>)           –            <p>The level of heading (e.g. 3 -&gt; <code>h3</code>).</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_heading(role)","level":4,"title":"<code>role</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>An optional role for the object bound to this heading.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_heading(hidden)","level":4,"title":"<code>hidden</code>","text":"(<code>bool</code>, default:                   <code>False</code> )           –            <p>If True, only register it for the table of contents, don't render anything.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_heading(toc_label)","level":4,"title":"<code>toc_label</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The title to use in the table of contents ('data-toc-label' attribute).</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_heading(skip_inventory)","level":4,"title":"<code>skip_inventory</code>","text":"(<code>bool</code>, default:                   <code>False</code> )           –            <p>Flag element to not be registered in the inventory (by setting a <code>data-skip-inventory</code> attribute).</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.do_heading(**attributes)","level":4,"title":"<code>**attributes</code>","text":"(<code>str</code>, default:                   <code>{}</code> )           –            <p>Any extra HTML attributes of the heading.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_aliases","level":3,"title":"get_aliases","text":"<pre><code>get_aliases(identifier: str) -&gt; tuple[str, ...]\n</code></pre> <p>Return the possible aliases for a given identifier.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>tuple[str, ...]</code>           –            <p>A tuple of strings - aliases.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_aliases(self, identifier: str) -&gt; tuple[str, ...]:  # noqa: ARG002\n    \"\"\"Return the possible aliases for a given identifier.\n\n    Arguments:\n        identifier: The identifier to get the aliases of.\n\n    Returns:\n        A tuple of strings - aliases.\n    \"\"\"\n    return ()\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_aliases(identifier)","level":4,"title":"<code>identifier</code>","text":"(<code>str</code>)           –            <p>The identifier to get the aliases of.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_extended_templates_dirs","level":3,"title":"get_extended_templates_dirs","text":"<pre><code>get_extended_templates_dirs(handler: str) -&gt; list[Path]\n</code></pre> <p>Load template extensions for the given handler, return their templates directories.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>list[Path]</code>           –            <p>The extensions templates directories.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_extended_templates_dirs(self, handler: str) -&gt; list[Path]:\n    \"\"\"Load template extensions for the given handler, return their templates directories.\n\n    Arguments:\n        handler: The name of the handler to get the extended templates directory of.\n\n    Returns:\n        The extensions templates directories.\n    \"\"\"\n    discovered_extensions = entry_points(group=f\"mkdocstrings.{handler}.templates\")\n    return [extension.load()() for extension in discovered_extensions]\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_extended_templates_dirs(handler)","level":4,"title":"<code>handler</code>","text":"(<code>str</code>)           –            <p>The name of the handler to get the extended templates directory of.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_headings","level":3,"title":"get_headings","text":"<pre><code>get_headings() -&gt; Sequence[Element]\n</code></pre> <p>Return and clear the headings gathered so far.</p> <p>Returns:</p> <ul> <li> <code>Sequence[Element]</code>           –            <p>A list of HTML elements.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_headings(self) -&gt; Sequence[Element]:\n    \"\"\"Return and clear the headings gathered so far.\n\n    Returns:\n        A list of HTML elements.\n    \"\"\"\n    result = list(self._headings)\n    self._headings.clear()\n    return result\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_inventory_urls","level":3,"title":"get_inventory_urls","text":"<pre><code>get_inventory_urls() -&gt; list[tuple[str, dict[str, Any]]]\n</code></pre> <p>Return the URLs (and configuration options) of the inventory files to download.</p> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_inventory_urls(self) -&gt; list[tuple[str, dict[str, Any]]]:\n    \"\"\"Return the URLs (and configuration options) of the inventory files to download.\"\"\"\n    return []\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_options","level":3,"title":"get_options","text":"<pre><code>get_options(\n    local_options: Mapping[str, Any],\n) -&gt; HandlerOptions\n</code></pre> <p>Get combined options.</p> <p>Override this method to customize how options are combined, for example by merging the global options with the local options. By combining options here, you don't have to do it twice in <code>collect</code> and <code>render</code>.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>HandlerOptions</code>           –            <p>The combined options.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_options(self, local_options: Mapping[str, Any]) -&gt; HandlerOptions:\n    \"\"\"Get combined options.\n\n    Override this method to customize how options are combined,\n    for example by merging the global options with the local options.\n    By combining options here, you don't have to do it twice in `collect` and `render`.\n\n    Arguments:\n        local_options: The local options.\n\n    Returns:\n        The combined options.\n    \"\"\"\n    return local_options\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_options(local_options)","level":4,"title":"<code>local_options</code>","text":"(<code>Mapping[str, Any]</code>)           –            <p>The local options.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_templates_dir","level":3,"title":"get_templates_dir","text":"<pre><code>get_templates_dir(handler: str | None = None) -&gt; Path\n</code></pre> <p>Return the path to the handler's templates directory.</p> <p>Override to customize how the templates directory is found.</p> <p>Parameters:</p> <p>Raises:</p> <ul> <li> <code>ModuleNotFoundError</code>             –            <p>When no such handler is installed.</p> </li> <li> <code>FileNotFoundError</code>             –            <p>When the templates directory cannot be found.</p> </li> </ul> <p>Returns:</p> <ul> <li> <code>Path</code>           –            <p>The templates directory path.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_templates_dir(self, handler: str | None = None) -&gt; Path:\n    \"\"\"Return the path to the handler's templates directory.\n\n    Override to customize how the templates directory is found.\n\n    Arguments:\n        handler: The name of the handler to get the templates directory of.\n\n    Raises:\n        ModuleNotFoundError: When no such handler is installed.\n        FileNotFoundError: When the templates directory cannot be found.\n\n    Returns:\n        The templates directory path.\n    \"\"\"\n    handler = handler or self.name\n    try:\n        import mkdocstrings_handlers  # noqa: PLC0415\n    except ModuleNotFoundError as error:\n        raise ModuleNotFoundError(f\"Handler '{handler}' not found, is it installed?\") from error\n\n    for path in mkdocstrings_handlers.__path__:\n        theme_path = Path(path, handler, \"templates\")\n        if theme_path.exists():\n            return theme_path\n\n    raise FileNotFoundError(f\"Can't find 'templates' folder for handler '{handler}'\")\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.get_templates_dir(handler)","level":4,"title":"<code>handler</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The name of the handler to get the templates directory of.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.load_inventory","level":3,"title":"load_inventory  <code>classmethod</code>","text":"<pre><code>load_inventory(\n    in_file: BinaryIO,\n    url: str,\n    base_url: str | None = None,\n    **kwargs: Any,\n) -&gt; Iterator[tuple[str, str]]\n</code></pre> <p>Yield items and their URLs from an inventory file streamed from <code>in_file</code>.</p> <p>Parameters:</p> <p>Yields:</p> <ul> <li> <code>tuple[str, str]</code>           –            <p>Tuples of (item identifier, item URL).</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>@classmethod\ndef load_inventory(\n    cls,\n    in_file: BinaryIO,  # noqa: ARG003\n    url: str,  # noqa: ARG003\n    base_url: str | None = None,  # noqa: ARG003\n    **kwargs: Any,  # noqa: ARG003\n) -&gt; Iterator[tuple[str, str]]:\n    \"\"\"Yield items and their URLs from an inventory file streamed from `in_file`.\n\n    Arguments:\n        in_file: The binary file-like object to read the inventory from.\n        url: The URL that this file is being streamed from (used to guess `base_url`).\n        base_url: The URL that this inventory's sub-paths are relative to.\n        **kwargs: Ignore additional arguments passed from the config.\n\n    Yields:\n        Tuples of (item identifier, item URL).\n    \"\"\"\n    yield from ()\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.load_inventory(in_file)","level":4,"title":"<code>in_file</code>","text":"(<code>BinaryIO</code>)           –            <p>The binary file-like object to read the inventory from.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.load_inventory(url)","level":4,"title":"<code>url</code>","text":"(<code>str</code>)           –            <p>The URL that this file is being streamed from (used to guess <code>base_url</code>).</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.load_inventory(base_url)","level":4,"title":"<code>base_url</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The URL that this inventory's sub-paths are relative to.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.load_inventory(**kwargs)","level":4,"title":"<code>**kwargs</code>","text":"(<code>Any</code>, default:                   <code>{}</code> )           –            <p>Ignore additional arguments passed from the config.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.render","level":3,"title":"render","text":"<pre><code>render(\n    data: CollectorItem,\n    options: HandlerOptions,\n    *,\n    locale: str | None = None,\n) -&gt; str\n</code></pre> <p>Render a template using provided data and configuration options.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>str</code>           –            <p>The rendered template as HTML.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def render(self, data: CollectorItem, options: HandlerOptions, *, locale: str | None = None) -&gt; str:\n    \"\"\"Render a template using provided data and configuration options.\n\n    Arguments:\n        data: The collected data to render.\n        options: The final configuration options.\n        locale: The locale to use for translations, if any.\n\n    Returns:\n        The rendered template as HTML.\n    \"\"\"\n    raise NotImplementedError\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.render(data)","level":4,"title":"<code>data</code>","text":"(<code>CollectorItem</code>)           –            <p>The collected data to render.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.render(options)","level":4,"title":"<code>options</code>","text":"(<code>HandlerOptions</code>)           –            <p>The final configuration options.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.render(locale)","level":4,"title":"<code>locale</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The locale to use for translations, if any.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.render_backlinks","level":3,"title":"render_backlinks","text":"<pre><code>render_backlinks(\n    backlinks: Mapping[str, Iterable[Backlink]],\n    *,\n    locale: str | None = None,\n) -&gt; str\n</code></pre> <p>Render backlinks.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>str</code>           –            <p>The rendered backlinks as HTML.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]], *, locale: str | None = None) -&gt; str:  # noqa: ARG002\n    \"\"\"Render backlinks.\n\n    Parameters:\n        backlinks: A mapping of identifiers to backlinks.\n        locale: The locale to use for translations, if any.\n\n    Returns:\n        The rendered backlinks as HTML.\n    \"\"\"\n    return \"\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.render_backlinks(backlinks)","level":4,"title":"<code>backlinks</code>","text":"(<code>Mapping[str, Iterable[Backlink]]</code>)           –            <p>A mapping of identifiers to backlinks.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.render_backlinks(locale)","level":4,"title":"<code>locale</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The locale to use for translations, if any.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.teardown","level":3,"title":"teardown","text":"<pre><code>teardown() -&gt; None\n</code></pre> <p>Teardown the handler.</p> <p>This method should be implemented to, for example, terminate a subprocess that was started when creating the handler instance.</p> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def teardown(self) -&gt; None:\n    \"\"\"Teardown the handler.\n\n    This method should be implemented to, for example, terminate a subprocess\n    that was started when creating the handler instance.\n    \"\"\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.BaseHandler.update_env","level":3,"title":"update_env","text":"<pre><code>update_env(config: Any) -&gt; None\n</code></pre> <p>Update the Jinja environment.</p> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def update_env(self, config: Any) -&gt; None:\n    \"\"\"Update the Jinja environment.\"\"\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.CollectionError","level":2,"title":"CollectionError","text":"<p>               Bases: <code>Exception</code></p> <p>An exception raised when some collection of data failed.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers","level":2,"title":"Handlers","text":"<pre><code>Handlers(\n    *,\n    theme: str,\n    default: str,\n    inventory_project: str,\n    inventory_version: str = \"0.0.0\",\n    handlers_config: dict[str, HandlerConfig] | None = None,\n    custom_templates: str | None = None,\n    mdx: Sequence[str | Extension] | None = None,\n    mdx_config: Mapping[str, Any] | None = None,\n    locale: str = \"en\",\n    tool_config: Any,\n)\n</code></pre> <p>A collection of handlers.</p> <p>Do not instantiate this directly. The plugin will keep one instance of this for the purpose of caching. Use mkdocstrings.MkdocstringsPlugin.get_handler for convenient access.</p> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>get_handler</code>             –              <p>Get a handler thanks to its name.</p> </li> <li> <code>get_handler_config</code>             –              <p>Return the global configuration of the given handler.</p> </li> <li> <code>get_handler_name</code>             –              <p>Return the handler name defined in an \"autodoc\" instruction YAML configuration, or the global default handler.</p> </li> <li> <code>teardown</code>             –              <p>Teardown all cached handlers and clear the cache.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>inventory</code>               (<code>Inventory</code>)           –            <p>The objects inventory.</p> </li> <li> <code>seen_handlers</code>               (<code>Iterable[BaseHandler]</code>)           –            <p>Get the handlers that were encountered so far throughout the build.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def __init__(\n    self,\n    *,\n    theme: str,\n    default: str,\n    inventory_project: str,\n    inventory_version: str = \"0.0.0\",\n    handlers_config: dict[str, HandlerConfig] | None = None,\n    custom_templates: str | None = None,\n    mdx: Sequence[str | Extension] | None = None,\n    mdx_config: Mapping[str, Any] | None = None,\n    locale: str = \"en\",\n    tool_config: Any,\n) -&gt; None:\n    \"\"\"Initialize the object.\n\n    Arguments:\n        theme: The theme to use.\n        default: The default handler to use.\n        inventory_project: The project name to use in the inventory.\n        inventory_version: The project version to use in the inventory.\n        handlers_config: The handlers configuration.\n        custom_templates: The path to custom templates.\n        mdx: A list of Markdown extensions to use.\n        mdx_config: Configuration for the Markdown extensions.\n        locale: The locale to use for translations.\n        tool_config: Tool configuration to pass down to handlers.\n    \"\"\"\n    self._theme = theme\n    self._default = default\n    self._handlers_config = handlers_config or {}\n    self._custom_templates = custom_templates\n    self._mdx = mdx or []\n    self._mdx_config = mdx_config or {}\n    self._handlers: dict[str, BaseHandler] = {}\n    self._locale = locale\n    self._tool_config = tool_config\n\n    self.inventory: Inventory = Inventory(project=inventory_project, version=inventory_version)\n    \"\"\"The objects inventory.\"\"\"\n\n    self._inv_futures: dict[futures.Future, tuple[BaseHandler, str, Any]] = {}\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(theme)","level":3,"title":"<code>theme</code>","text":"(<code>str</code>)           –            <p>The theme to use.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(default)","level":3,"title":"<code>default</code>","text":"(<code>str</code>)           –            <p>The default handler to use.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(inventory_project)","level":3,"title":"<code>inventory_project</code>","text":"(<code>str</code>)           –            <p>The project name to use in the inventory.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(inventory_version)","level":3,"title":"<code>inventory_version</code>","text":"(<code>str</code>, default:                   <code>'0.0.0'</code> )           –            <p>The project version to use in the inventory.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(handlers_config)","level":3,"title":"<code>handlers_config</code>","text":"(<code>dict[str, HandlerConfig] | None</code>, default:                   <code>None</code> )           –            <p>The handlers configuration.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(custom_templates)","level":3,"title":"<code>custom_templates</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The path to custom templates.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(mdx)","level":3,"title":"<code>mdx</code>","text":"(<code>Sequence[str | Extension] | None</code>, default:                   <code>None</code> )           –            <p>A list of Markdown extensions to use.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(mdx_config)","level":3,"title":"<code>mdx_config</code>","text":"(<code>Mapping[str, Any] | None</code>, default:                   <code>None</code> )           –            <p>Configuration for the Markdown extensions.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(locale)","level":3,"title":"<code>locale</code>","text":"(<code>str</code>, default:                   <code>'en'</code> )           –            <p>The locale to use for translations.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers(tool_config)","level":3,"title":"<code>tool_config</code>","text":"(<code>Any</code>)           –            <p>Tool configuration to pass down to handlers.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.inventory","level":3,"title":"inventory  <code>instance-attribute</code>","text":"<pre><code>inventory: Inventory = Inventory(\n    project=inventory_project, version=inventory_version\n)\n</code></pre> <p>The objects inventory.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.seen_handlers","level":3,"title":"seen_handlers  <code>property</code>","text":"<pre><code>seen_handlers: Iterable[BaseHandler]\n</code></pre> <p>Get the handlers that were encountered so far throughout the build.</p> <p>Returns:</p> <ul> <li> <code>Iterable[BaseHandler]</code>           –            <p>An iterable of instances of <code>BaseHandler</code></p> </li> <li> <code>Iterable[BaseHandler]</code>           –            <p>(usable only to loop through it).</p> </li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.get_handler","level":3,"title":"get_handler","text":"<pre><code>get_handler(\n    name: str, handler_config: dict | None = None\n) -&gt; BaseHandler\n</code></pre> <p>Get a handler thanks to its name.</p> <p>This function dynamically imports a module named \"mkdocstrings_handlers.NAME\", calls its <code>get_handler</code> method to get an instance of a handler, and caches it in dictionary. It means that during one run (for each reload when serving, or once when building), a handler is instantiated only once, and reused for each \"autodoc\" instruction asking for it.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>BaseHandler</code>           –            <p>An instance of a subclass of <code>BaseHandler</code>, as instantiated by the <code>get_handler</code> method of the handler's module.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_handler(self, name: str, handler_config: dict | None = None) -&gt; BaseHandler:\n    \"\"\"Get a handler thanks to its name.\n\n    This function dynamically imports a module named \"mkdocstrings_handlers.NAME\", calls its\n    `get_handler` method to get an instance of a handler, and caches it in dictionary.\n    It means that during one run (for each reload when serving, or once when building),\n    a handler is instantiated only once, and reused for each \"autodoc\" instruction asking for it.\n\n    Arguments:\n        name: The name of the handler. Really, it's the name of the Python module holding it.\n        handler_config: Configuration passed to the handler.\n\n    Returns:\n        An instance of a subclass of [`BaseHandler`][mkdocstrings.BaseHandler],\n            as instantiated by the `get_handler` method of the handler's module.\n    \"\"\"\n    if name not in self._handlers:\n        if handler_config is None:\n            handler_config = self._handlers_config.get(name, {})\n        module = importlib.import_module(f\"mkdocstrings_handlers.{name}\")\n\n        self._handlers[name] = module.get_handler(\n            theme=self._theme,\n            custom_templates=self._custom_templates,\n            mdx=self._mdx,\n            mdx_config=self._mdx_config,\n            handler_config=handler_config,\n            tool_config=self._tool_config,\n        )\n    return self._handlers[name]\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.get_handler(name)","level":4,"title":"<code>name</code>","text":"(<code>str</code>)           –            <p>The name of the handler. Really, it's the name of the Python module holding it.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.get_handler(handler_config)","level":4,"title":"<code>handler_config</code>","text":"(<code>dict | None</code>, default:                   <code>None</code> )           –            <p>Configuration passed to the handler.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.get_handler_config","level":3,"title":"get_handler_config","text":"<pre><code>get_handler_config(name: str) -&gt; dict\n</code></pre> <p>Return the global configuration of the given handler.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>dict</code>           –            <p>The global configuration of the given handler. It can be an empty dictionary.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_handler_config(self, name: str) -&gt; dict:\n    \"\"\"Return the global configuration of the given handler.\n\n    Arguments:\n        name: The name of the handler to get the global configuration of.\n\n    Returns:\n        The global configuration of the given handler. It can be an empty dictionary.\n    \"\"\"\n    return self._handlers_config.get(name, None) or {}\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.get_handler_config(name)","level":4,"title":"<code>name</code>","text":"(<code>str</code>)           –            <p>The name of the handler to get the global configuration of.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.get_handler_name","level":3,"title":"get_handler_name","text":"<pre><code>get_handler_name(config: dict) -&gt; str\n</code></pre> <p>Return the handler name defined in an \"autodoc\" instruction YAML configuration, or the global default handler.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>str</code>           –            <p>The name of the handler to use.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def get_handler_name(self, config: dict) -&gt; str:\n    \"\"\"Return the handler name defined in an \"autodoc\" instruction YAML configuration, or the global default handler.\n\n    Arguments:\n        config: A configuration dictionary, obtained from YAML below the \"autodoc\" instruction.\n\n    Returns:\n        The name of the handler to use.\n    \"\"\"\n    return config.get(\"handler\", self._default)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.get_handler_name(config)","level":4,"title":"<code>config</code>","text":"(<code>dict</code>)           –            <p>A configuration dictionary, obtained from YAML below the \"autodoc\" instruction.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Handlers.teardown","level":3,"title":"teardown","text":"<pre><code>teardown() -&gt; None\n</code></pre> <p>Teardown all cached handlers and clear the cache.</p> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def teardown(self) -&gt; None:\n    \"\"\"Teardown all cached handlers and clear the cache.\"\"\"\n    for future in self._inv_futures:\n        future.cancel()\n    for handler in self.seen_handlers:\n        handler.teardown()\n    self._handlers.clear()\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HeadingShiftingTreeprocessor","level":2,"title":"HeadingShiftingTreeprocessor","text":"<pre><code>HeadingShiftingTreeprocessor(md: Markdown, shift_by: int)\n</code></pre> <p>               Bases: <code>Treeprocessor</code></p> <p>Shift levels of all Markdown headings according to the configured base level.</p> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>run</code>             –              <p>Shift the levels of all headings in the document.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>name</code>               (<code>str</code>)           –            <p>The name of the treeprocessor.</p> </li> <li> <code>regex</code>               (<code>Pattern</code>)           –            <p>The regex to match heading tags.</p> </li> <li> <code>shift_by</code>               (<code>int</code>)           –            <p>The number of heading \"levels\" to add to every heading. <code>&lt;h2&gt;</code> with <code>shift_by = 3</code> becomes <code>&lt;h5&gt;</code>.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def __init__(self, md: Markdown, shift_by: int):\n    \"\"\"Initialize the object.\n\n    Arguments:\n        md: A `markdown.Markdown` instance.\n        shift_by: The number of heading \"levels\" to add to every heading.\n    \"\"\"\n    super().__init__(md)\n    self.shift_by = shift_by\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HeadingShiftingTreeprocessor(md)","level":3,"title":"<code>md</code>","text":"(<code>Markdown</code>)           –            <p>A <code>markdown.Markdown</code> instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HeadingShiftingTreeprocessor(shift_by)","level":3,"title":"<code>shift_by</code>","text":"(<code>int</code>)           –            <p>The number of heading \"levels\" to add to every heading.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HeadingShiftingTreeprocessor.name","level":3,"title":"name  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>name: str = 'mkdocstrings_headings'\n</code></pre> <p>The name of the treeprocessor.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HeadingShiftingTreeprocessor.regex","level":3,"title":"regex  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>regex: Pattern = compile('([Hh])([1-6])')\n</code></pre> <p>The regex to match heading tags.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HeadingShiftingTreeprocessor.shift_by","level":3,"title":"shift_by  <code>instance-attribute</code>","text":"<pre><code>shift_by: int = shift_by\n</code></pre> <p>The number of heading \"levels\" to add to every heading. <code>&lt;h2&gt;</code> with <code>shift_by = 3</code> becomes <code>&lt;h5&gt;</code>.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.HeadingShiftingTreeprocessor.run","level":3,"title":"run","text":"<pre><code>run(root: Element) -&gt; None\n</code></pre> <p>Shift the levels of all headings in the document.</p> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def run(self, root: Element) -&gt; None:\n    \"\"\"Shift the levels of all headings in the document.\"\"\"\n    if not self.shift_by:\n        return\n    for el in root.iter():\n        match = self.regex.fullmatch(el.tag)\n        if match:\n            level = int(match[2]) + self.shift_by\n            level = max(1, min(level, 6))\n            el.tag = f\"{match[1]}{level}\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter","level":2,"title":"Highlighter","text":"<pre><code>Highlighter(md: Markdown)\n</code></pre> <p>               Bases: <code>Highlight</code></p> <p>Code highlighter that tries to match the Markdown configuration.</p> <p>Picking up the global config and defaults works only if you use the <code>codehilite</code> or <code>pymdownx.highlight</code> (recommended) Markdown extension.</p> <ul> <li> <p>If you use <code>pymdownx.highlight</code>, highlighting settings are picked up from it, and the     default CSS class is <code>.highlight</code>. This also means the default of <code>guess_lang: false</code>.</p> </li> <li> <p>Otherwise, if you use the <code>codehilite</code> extension, settings are picked up from it, and the     default CSS class is <code>.codehilite</code>. Also consider setting <code>guess_lang: false</code>.</p> </li> <li> <p>If neither are added to <code>markdown_extensions</code>, highlighting is enabled anyway. This is for     backwards compatibility. If you really want to disable highlighting even in mkdocstrings,     add one of these extensions anyway and set <code>use_pygments: false</code>.</p> </li> </ul> <p>The underlying implementation is <code>pymdownx.highlight</code> regardless.</p> <p>Parameters:</p> <ul> <li> </li> </ul> <p>Methods:</p> <ul> <li> <code>highlight</code>             –              <p>Highlight a code-snippet.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def __init__(self, md: Markdown):\n    \"\"\"Configure to match a `markdown.Markdown` instance.\n\n    Arguments:\n        md: The Markdown instance to read configs from.\n    \"\"\"\n    config: dict[str, Any] = {}\n    self._highlighter: str | None = None\n    for ext in md.registeredExtensions:\n        if isinstance(ext, HighlightExtension) and (ext.enabled or not config):\n            self._highlighter = \"highlight\"\n            config = ext.getConfigs()\n            break  # This one takes priority, no need to continue looking\n        if isinstance(ext, CodeHiliteExtension) and not config:\n            self._highlighter = \"codehilite\"\n            config = ext.getConfigs()\n            config[\"language_prefix\"] = config[\"lang_prefix\"]\n    self._css_class = config.pop(\"css_class\", \"highlight\")\n    super().__init__(**{name: opt for name, opt in config.items() if name in self._highlight_config_keys})\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter(md)","level":3,"title":"<code>md</code>","text":"(<code>Markdown</code>)           –            <p>The Markdown instance to read configs from.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter.highlight","level":3,"title":"highlight","text":"<pre><code>highlight(\n    src: str,\n    language: str | None = None,\n    *,\n    inline: bool = False,\n    dedent: bool = True,\n    linenums: bool | None = None,\n    **kwargs: Any,\n) -&gt; str\n</code></pre> <p>Highlight a code-snippet.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>str</code>           –            <p>The highlighted code as HTML text, marked safe (not escaped for HTML).</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def highlight(  # ty: ignore[invalid-method-override]\n    self,\n    src: str,\n    language: str | None = None,\n    *,\n    inline: bool = False,\n    dedent: bool = True,\n    linenums: bool | None = None,\n    **kwargs: Any,\n) -&gt; str:\n    \"\"\"Highlight a code-snippet.\n\n    Arguments:\n        src: The code to highlight.\n        language: Explicitly tell what language to use for highlighting.\n        inline: Whether to highlight as inline.\n        dedent: Whether to dedent the code before highlighting it or not.\n        linenums: Whether to add line numbers in the result.\n        **kwargs: Pass on to `pymdownx.highlight.Highlight.highlight`.\n\n    Returns:\n        The highlighted code as HTML text, marked safe (not escaped for HTML).\n    \"\"\"\n    if isinstance(src, Markup):\n        src = src.unescape()\n    if dedent:\n        src = textwrap.dedent(src)\n\n    kwargs.setdefault(\"css_class\", self._css_class)\n    old_linenums = self.linenums\n    if linenums is not None:\n        self.linenums = linenums\n    try:\n        result = super().highlight(src, language, inline=inline, **kwargs)\n    finally:\n        self.linenums = old_linenums\n\n    if inline:\n        # From the maintainer of codehilite, the codehilite CSS class, as defined by the user,\n        # should never be added to inline code, because codehilite does not support inline code.\n        # See https://github.com/Python-Markdown/markdown/issues/1220#issuecomment-1692160297.\n        css_class = \"\" if self._highlighter == \"codehilite\" else kwargs[\"css_class\"]\n        return Markup(f'&lt;code class=\"{css_class} language-{language}\"&gt;{result.text}&lt;/code&gt;')\n    return Markup(result)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter.highlight(src)","level":4,"title":"<code>src</code>","text":"(<code>str</code>)           –            <p>The code to highlight.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter.highlight(language)","level":4,"title":"<code>language</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>Explicitly tell what language to use for highlighting.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter.highlight(inline)","level":4,"title":"<code>inline</code>","text":"(<code>bool</code>, default:                   <code>False</code> )           –            <p>Whether to highlight as inline.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter.highlight(dedent)","level":4,"title":"<code>dedent</code>","text":"(<code>bool</code>, default:                   <code>True</code> )           –            <p>Whether to dedent the code before highlighting it or not.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter.highlight(linenums)","level":4,"title":"<code>linenums</code>","text":"(<code>bool | None</code>, default:                   <code>None</code> )           –            <p>Whether to add line numbers in the result.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Highlighter.highlight(**kwargs)","level":4,"title":"<code>**kwargs</code>","text":"(<code>Any</code>, default:                   <code>{}</code> )           –            <p>Pass on to <code>pymdownx.highlight.Highlight.highlight</code>.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.IdPrependingTreeprocessor","level":2,"title":"IdPrependingTreeprocessor","text":"<pre><code>IdPrependingTreeprocessor(md: Markdown, id_prefix: str)\n</code></pre> <p>               Bases: <code>Treeprocessor</code></p> <p>Prepend the configured prefix to IDs of all HTML elements.</p> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>run</code>             –              <p>Prepend the configured prefix to all IDs in the document.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>id_prefix</code>               (<code>str</code>)           –            <p>The prefix to add to every ID. It is prepended without any separator; specify your own separator if needed.</p> </li> <li> <code>name</code>               (<code>str</code>)           –            <p>The name of the treeprocessor.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def __init__(self, md: Markdown, id_prefix: str):\n    \"\"\"Initialize the object.\n\n    Arguments:\n        md: A `markdown.Markdown` instance.\n        id_prefix: The prefix to add to every ID. It is prepended without any separator.\n    \"\"\"\n    super().__init__(md)\n    self.id_prefix = id_prefix\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.IdPrependingTreeprocessor(md)","level":3,"title":"<code>md</code>","text":"(<code>Markdown</code>)           –            <p>A <code>markdown.Markdown</code> instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.IdPrependingTreeprocessor(id_prefix)","level":3,"title":"<code>id_prefix</code>","text":"(<code>str</code>)           –            <p>The prefix to add to every ID. It is prepended without any separator.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.IdPrependingTreeprocessor.id_prefix","level":3,"title":"id_prefix  <code>instance-attribute</code>","text":"<pre><code>id_prefix: str = id_prefix\n</code></pre> <p>The prefix to add to every ID. It is prepended without any separator; specify your own separator if needed.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.IdPrependingTreeprocessor.name","level":3,"title":"name  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>name: str = 'mkdocstrings_ids'\n</code></pre> <p>The name of the treeprocessor.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.IdPrependingTreeprocessor.run","level":3,"title":"run","text":"<pre><code>run(root: Element) -&gt; None\n</code></pre> <p>Prepend the configured prefix to all IDs in the document.</p> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def run(self, root: Element) -&gt; None:\n    \"\"\"Prepend the configured prefix to all IDs in the document.\"\"\"\n    if self.id_prefix:\n        self._prefix_ids(root)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory","level":2,"title":"Inventory","text":"<pre><code>Inventory(\n    items: list[InventoryItem] | None = None,\n    project: str = \"project\",\n    version: str = \"0.0.0\",\n)\n</code></pre> <p>               Bases: <code>dict</code></p> <p>Inventory of collected and rendered objects.</p> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>format_sphinx</code>             –              <p>Format this inventory as a Sphinx <code>objects.inv</code> file.</p> </li> <li> <code>parse_sphinx</code>             –              <p>Parse a Sphinx v2 inventory file and return an <code>Inventory</code> from it.</p> </li> <li> <code>register</code>             –              <p>Create and register an item.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>project</code>           –            <p>The project name.</p> </li> <li> <code>version</code>           –            <p>The project version.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/inventory.py</code> <pre><code>def __init__(self, items: list[InventoryItem] | None = None, project: str = \"project\", version: str = \"0.0.0\"):\n    \"\"\"Initialize the object.\n\n    Arguments:\n        items: A list of items.\n        project: The project name.\n        version: The project version.\n    \"\"\"\n    super().__init__()\n    items = items or []\n    for item in items:\n        self[item.name] = item\n    self.project = project\n    \"\"\"The project name.\"\"\"\n    self.version = version\n    \"\"\"The project version.\"\"\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory(items)","level":3,"title":"<code>items</code>","text":"(<code>list[InventoryItem] | None</code>, default:                   <code>None</code> )           –            <p>A list of items.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory(project)","level":3,"title":"<code>project</code>","text":"(<code>str</code>, default:                   <code>'project'</code> )           –            <p>The project name.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory(version)","level":3,"title":"<code>version</code>","text":"(<code>str</code>, default:                   <code>'0.0.0'</code> )           –            <p>The project version.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.project","level":3,"title":"project  <code>instance-attribute</code>","text":"<pre><code>project = project\n</code></pre> <p>The project name.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.version","level":3,"title":"version  <code>instance-attribute</code>","text":"<pre><code>version = version\n</code></pre> <p>The project version.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.format_sphinx","level":3,"title":"format_sphinx","text":"<pre><code>format_sphinx() -&gt; bytes\n</code></pre> <p>Format this inventory as a Sphinx <code>objects.inv</code> file.</p> <p>Returns:</p> <ul> <li> <code>bytes</code>           –            <p>The inventory as bytes.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/inventory.py</code> <pre><code>def format_sphinx(self) -&gt; bytes:\n    \"\"\"Format this inventory as a Sphinx `objects.inv` file.\n\n    Returns:\n        The inventory as bytes.\n    \"\"\"\n    header = (\n        dedent(\n            f\"\"\"\n            # Sphinx inventory version 2\n            # Project: {self.project}\n            # Version: {self.version}\n            # The remainder of this file is compressed using zlib.\n            \"\"\",\n        )\n        .lstrip()\n        .encode(\"utf8\")\n    )\n\n    lines = [\n        item.format_sphinx().encode(\"utf8\")\n        for item in sorted(self.values(), key=lambda item: (item.domain, item.name))\n    ]\n    return header + zlib.compress(b\"\\n\".join(lines) + b\"\\n\", 9)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.parse_sphinx","level":3,"title":"parse_sphinx  <code>classmethod</code>","text":"<pre><code>parse_sphinx(\n    in_file: BinaryIO,\n    *,\n    domain_filter: Collection[str] = (),\n) -&gt; Inventory\n</code></pre> <p>Parse a Sphinx v2 inventory file and return an <code>Inventory</code> from it.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>Inventory</code>           –            <p>An inventory containing the collected items.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/inventory.py</code> <pre><code>@classmethod\ndef parse_sphinx(cls, in_file: BinaryIO, *, domain_filter: Collection[str] = ()) -&gt; Inventory:\n    \"\"\"Parse a Sphinx v2 inventory file and return an `Inventory` from it.\n\n    Arguments:\n        in_file: The binary file-like object to read from.\n        domain_filter: A collection of domain values to allow (and filter out all other ones).\n\n    Returns:\n        An inventory containing the collected items.\n    \"\"\"\n    for _ in range(4):\n        in_file.readline()\n    lines = zlib.decompress(in_file.read()).splitlines()\n    items: list[InventoryItem] = [\n        item for line in lines if (item := InventoryItem.parse_sphinx(line.decode(\"utf8\"), return_none=True))\n    ]\n    if domain_filter:\n        items = [item for item in items if item.domain in domain_filter]\n    return cls(items)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.parse_sphinx(in_file)","level":4,"title":"<code>in_file</code>","text":"(<code>BinaryIO</code>)           –            <p>The binary file-like object to read from.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.parse_sphinx(domain_filter)","level":4,"title":"<code>domain_filter</code>","text":"(<code>Collection[str]</code>, default:                   <code>()</code> )           –            <p>A collection of domain values to allow (and filter out all other ones).</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.register","level":3,"title":"register","text":"<pre><code>register(\n    name: str,\n    domain: str,\n    role: str,\n    uri: str,\n    priority: int = 1,\n    dispname: str | None = None,\n) -&gt; None\n</code></pre> <p>Create and register an item.</p> <p>Parameters:</p> Source code in <code>src/mkdocstrings/_internal/inventory.py</code> <pre><code>def register(\n    self,\n    name: str,\n    domain: str,\n    role: str,\n    uri: str,\n    priority: int = 1,\n    dispname: str | None = None,\n) -&gt; None:\n    \"\"\"Create and register an item.\n\n    Arguments:\n        name: The item name.\n        domain: The item domain, like 'python' or 'crystal'.\n        role: The item role, like 'class' or 'method'.\n        uri: The item URI.\n        priority: The item priority. Only used internally by mkdocstrings and Sphinx.\n        dispname: The item display name.\n    \"\"\"\n    self[name] = InventoryItem(\n        name=name,\n        domain=domain,\n        role=role,\n        uri=uri,\n        priority=priority,\n        dispname=dispname,\n    )\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.register(name)","level":4,"title":"<code>name</code>","text":"(<code>str</code>)           –            <p>The item name.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.register(domain)","level":4,"title":"<code>domain</code>","text":"(<code>str</code>)           –            <p>The item domain, like 'python' or 'crystal'.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.register(role)","level":4,"title":"<code>role</code>","text":"(<code>str</code>)           –            <p>The item role, like 'class' or 'method'.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.register(uri)","level":4,"title":"<code>uri</code>","text":"(<code>str</code>)           –            <p>The item URI.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.register(priority)","level":4,"title":"<code>priority</code>","text":"(<code>int</code>, default:                   <code>1</code> )           –            <p>The item priority. Only used internally by mkdocstrings and Sphinx.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.Inventory.register(dispname)","level":4,"title":"<code>dispname</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The item display name.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem","level":2,"title":"InventoryItem","text":"<pre><code>InventoryItem(\n    name: str,\n    domain: str,\n    role: str,\n    uri: str,\n    priority: int = 1,\n    dispname: str | None = None,\n)\n</code></pre> <p>Inventory item.</p> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>format_sphinx</code>             –              <p>Format this item as a Sphinx inventory line.</p> </li> <li> <code>parse_sphinx</code>             –              <p>Parse a line from a Sphinx v2 inventory file and return an <code>InventoryItem</code> from it.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>dispname</code>               (<code>str</code>)           –            <p>The item display name.</p> </li> <li> <code>domain</code>               (<code>str</code>)           –            <p>The item domain.</p> </li> <li> <code>name</code>               (<code>str</code>)           –            <p>The item name.</p> </li> <li> <code>priority</code>               (<code>int</code>)           –            <p>The item priority.</p> </li> <li> <code>role</code>               (<code>str</code>)           –            <p>The item role.</p> </li> <li> <code>sphinx_item_regex</code>           –            <p>Regex to parse a Sphinx v2 inventory line.</p> </li> <li> <code>uri</code>               (<code>str</code>)           –            <p>The item URI.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/inventory.py</code> <pre><code>def __init__(\n    self,\n    name: str,\n    domain: str,\n    role: str,\n    uri: str,\n    priority: int = 1,\n    dispname: str | None = None,\n):\n    \"\"\"Initialize the object.\n\n    Arguments:\n        name: The item name.\n        domain: The item domain, like 'python' or 'crystal'.\n        role: The item role, like 'class' or 'method'.\n        uri: The item URI.\n        priority: The item priority. Only used internally by mkdocstrings and Sphinx.\n        dispname: The item display name.\n    \"\"\"\n    self.name: str = name\n    \"\"\"The item name.\"\"\"\n    self.domain: str = domain\n    \"\"\"The item domain.\"\"\"\n    self.role: str = role\n    \"\"\"The item role.\"\"\"\n    self.uri: str = uri\n    \"\"\"The item URI.\"\"\"\n    self.priority: int = priority\n    \"\"\"The item priority.\"\"\"\n    self.dispname: str = dispname or name\n    \"\"\"The item display name.\"\"\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem(name)","level":3,"title":"<code>name</code>","text":"(<code>str</code>)           –            <p>The item name.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem(domain)","level":3,"title":"<code>domain</code>","text":"(<code>str</code>)           –            <p>The item domain, like 'python' or 'crystal'.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem(role)","level":3,"title":"<code>role</code>","text":"(<code>str</code>)           –            <p>The item role, like 'class' or 'method'.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem(uri)","level":3,"title":"<code>uri</code>","text":"(<code>str</code>)           –            <p>The item URI.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem(priority)","level":3,"title":"<code>priority</code>","text":"(<code>int</code>, default:                   <code>1</code> )           –            <p>The item priority. Only used internally by mkdocstrings and Sphinx.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem(dispname)","level":3,"title":"<code>dispname</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The item display name.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.dispname","level":3,"title":"dispname  <code>instance-attribute</code>","text":"<pre><code>dispname: str = dispname or name\n</code></pre> <p>The item display name.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.domain","level":3,"title":"domain  <code>instance-attribute</code>","text":"<pre><code>domain: str = domain\n</code></pre> <p>The item domain.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.name","level":3,"title":"name  <code>instance-attribute</code>","text":"<pre><code>name: str = name\n</code></pre> <p>The item name.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.priority","level":3,"title":"priority  <code>instance-attribute</code>","text":"<pre><code>priority: int = priority\n</code></pre> <p>The item priority.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.role","level":3,"title":"role  <code>instance-attribute</code>","text":"<pre><code>role: str = role\n</code></pre> <p>The item role.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.sphinx_item_regex","level":3,"title":"sphinx_item_regex  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>sphinx_item_regex = compile(\n    \"^(.+?)\\\\s+(\\\\S+):(\\\\S+)\\\\s+(-?\\\\d+)\\\\s+(\\\\S+)\\\\s*(.*)$\"\n)\n</code></pre> <p>Regex to parse a Sphinx v2 inventory line.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.uri","level":3,"title":"uri  <code>instance-attribute</code>","text":"<pre><code>uri: str = uri\n</code></pre> <p>The item URI.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.format_sphinx","level":3,"title":"format_sphinx","text":"<pre><code>format_sphinx() -&gt; str\n</code></pre> <p>Format this item as a Sphinx inventory line.</p> <p>Returns:</p> <ul> <li> <code>str</code>           –            <p>A line formatted for an <code>objects.inv</code> file.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/inventory.py</code> <pre><code>def format_sphinx(self) -&gt; str:\n    \"\"\"Format this item as a Sphinx inventory line.\n\n    Returns:\n        A line formatted for an `objects.inv` file.\n    \"\"\"\n    dispname = self.dispname\n    if dispname == self.name:\n        dispname = \"-\"\n    uri = self.uri\n    if uri.endswith(self.name):\n        uri = uri[: -len(self.name)] + \"$\"\n    return f\"{self.name} {self.domain}:{self.role} {self.priority} {uri} {dispname}\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.InventoryItem.parse_sphinx","level":3,"title":"parse_sphinx  <code>classmethod</code>","text":"<pre><code>parse_sphinx(\n    line: str, *, return_none: Literal[False]\n) -&gt; InventoryItem\n</code></pre><pre><code>parse_sphinx(\n    line: str, *, return_none: Literal[True]\n) -&gt; InventoryItem | None\n</code></pre> <pre><code>parse_sphinx(\n    line: str, *, return_none: bool = False\n) -&gt; InventoryItem | None\n</code></pre> <p>Parse a line from a Sphinx v2 inventory file and return an <code>InventoryItem</code> from it.</p> Source code in <code>src/mkdocstrings/_internal/inventory.py</code> <pre><code>@classmethod\ndef parse_sphinx(cls, line: str, *, return_none: bool = False) -&gt; InventoryItem | None:\n    \"\"\"Parse a line from a Sphinx v2 inventory file and return an `InventoryItem` from it.\"\"\"\n    match = cls.sphinx_item_regex.search(line)\n    if not match:\n        if return_none:\n            return None\n        raise ValueError(line)\n    name, domain, role, priority, uri, dispname = match.groups()\n    if uri.endswith(\"$\"):\n        uri = uri[:-1] + name\n    if dispname == \"-\":\n        dispname = name\n    return cls(name, domain, role, uri, int(priority), dispname)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter","level":2,"title":"LoggerAdapter","text":"<pre><code>LoggerAdapter(prefix: str, logger: Logger)\n</code></pre> <p>               Bases: <code>LoggerAdapter</code></p> <p>A logger adapter to prefix messages.</p> <p>This adapter also adds an additional parameter to logging methods called <code>once</code>: if <code>True</code>, the message will only be logged once.</p> <p>Examples:</p> <p>In Python code:</p> <pre><code>&gt;&gt;&gt; logger = get_logger(\"myplugin\")\n&gt;&gt;&gt; logger.debug(\"This is a debug message.\")\n&gt;&gt;&gt; logger.info(\"This is an info message.\", once=True)\n</code></pre> <p>In Jinja templates (logger available in context as <code>log</code>):</p> <pre><code>{{ log.debug(\"This is a debug message.\") }}\n{{ log.info(\"This is an info message.\", once=True) }}\n</code></pre> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>log</code>             –              <p>Log a message.</p> </li> <li> <code>process</code>             –              <p>Process the message.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>prefix</code>           –            <p>The prefix to insert in front of every message.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/loggers.py</code> <pre><code>def __init__(self, prefix: str, logger: logging.Logger):\n    \"\"\"Initialize the object.\n\n    Arguments:\n        prefix: The string to insert in front of every message.\n        logger: The logger instance.\n    \"\"\"\n    super().__init__(logger, {})\n    self.prefix = prefix\n    \"\"\"The prefix to insert in front of every message.\"\"\"\n    self._logged: set[tuple[LoggerAdapter, str]] = set()\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter(prefix)","level":3,"title":"<code>prefix</code>","text":"(<code>str</code>)           –            <p>The string to insert in front of every message.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter(logger)","level":3,"title":"<code>logger</code>","text":"(<code>Logger</code>)           –            <p>The logger instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.prefix","level":3,"title":"prefix  <code>instance-attribute</code>","text":"<pre><code>prefix = prefix\n</code></pre> <p>The prefix to insert in front of every message.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.log","level":3,"title":"log","text":"<pre><code>log(\n    level: int, msg: object, *args: object, **kwargs: object\n) -&gt; None\n</code></pre> <p>Log a message.</p> <p>Parameters:</p> Source code in <code>src/mkdocstrings/_internal/loggers.py</code> <pre><code>def log(self, level: int, msg: object, *args: object, **kwargs: object) -&gt; None:\n    \"\"\"Log a message.\n\n    Arguments:\n        level: The logging level.\n        msg: The message.\n        *args: Additional arguments passed to parent method.\n        **kwargs: Additional keyword arguments passed to parent method.\n    \"\"\"\n    if kwargs.pop(\"once\", False):\n        if (key := (self, str(msg))) in self._logged:\n            return\n        self._logged.add(key)\n    super().log(level, msg, *args, **kwargs)  # ty: ignore[invalid-argument-type]\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.log(level)","level":4,"title":"<code>level</code>","text":"(<code>int</code>)           –            <p>The logging level.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.log(msg)","level":4,"title":"<code>msg</code>","text":"(<code>object</code>)           –            <p>The message.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.log(*args)","level":4,"title":"<code>*args</code>","text":"(<code>object</code>, default:                   <code>()</code> )           –            <p>Additional arguments passed to parent method.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.log(**kwargs)","level":4,"title":"<code>**kwargs</code>","text":"(<code>object</code>, default:                   <code>{}</code> )           –            <p>Additional keyword arguments passed to parent method.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.process","level":3,"title":"process","text":"<pre><code>process(\n    msg: str, kwargs: MutableMapping[str, Any]\n) -&gt; tuple[str, Any]\n</code></pre> <p>Process the message.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>tuple[str, Any]</code>           –            <p>The processed message.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/loggers.py</code> <pre><code>def process(self, msg: str, kwargs: MutableMapping[str, Any]) -&gt; tuple[str, Any]:\n    \"\"\"Process the message.\n\n    Arguments:\n        msg: The message:\n        kwargs: Remaining arguments.\n\n    Returns:\n        The processed message.\n    \"\"\"\n    return f\"{self.prefix}: {msg}\", kwargs\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.process(msg)","level":4,"title":"<code>msg</code>","text":"(<code>str</code>)           –            <p>The message:</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.LoggerAdapter.process(kwargs)","level":4,"title":"<code>kwargs</code>","text":"(<code>MutableMapping[str, Any]</code>)           –            <p>Remaining arguments.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsExtension","level":2,"title":"MkdocstringsExtension","text":"<pre><code>MkdocstringsExtension(\n    handlers: Handlers,\n    autorefs: AutorefsPlugin,\n    *,\n    autorefs_extension: bool = False,\n    **kwargs: Any,\n)\n</code></pre> <p>               Bases: <code>Extension</code></p> <p>Our Markdown extension.</p> <p>It cannot work outside of <code>mkdocstrings</code>.</p> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>extendMarkdown</code>             –              <p>Register the extension.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/extension.py</code> <pre><code>def __init__(\n    self,\n    handlers: Handlers,\n    autorefs: AutorefsPlugin,\n    *,\n    autorefs_extension: bool = False,\n    **kwargs: Any,\n) -&gt; None:\n    \"\"\"Initialize the object.\n\n    Arguments:\n        handlers: The handlers container.\n        autorefs: The autorefs plugin instance.\n        autorefs_extension: Whether the autorefs extension must be registered.\n        **kwargs: Keyword arguments used by `markdown.extensions.Extension`.\n    \"\"\"\n    super().__init__(**kwargs)\n    self._handlers = handlers\n    self._autorefs = autorefs\n    self._autorefs_extension = autorefs_extension\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsExtension(handlers)","level":3,"title":"<code>handlers</code>","text":"(<code>Handlers</code>)           –            <p>The handlers container.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsExtension(autorefs)","level":3,"title":"<code>autorefs</code>","text":"(<code>AutorefsPlugin</code>)           –            <p>The autorefs plugin instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsExtension(autorefs_extension)","level":3,"title":"<code>autorefs_extension</code>","text":"(<code>bool</code>, default:                   <code>False</code> )           –            <p>Whether the autorefs extension must be registered.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsExtension(**kwargs)","level":3,"title":"<code>**kwargs</code>","text":"(<code>Any</code>, default:                   <code>{}</code> )           –            <p>Keyword arguments used by <code>markdown.extensions.Extension</code>.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsExtension.extendMarkdown","level":3,"title":"extendMarkdown","text":"<pre><code>extendMarkdown(md: Markdown) -&gt; None\n</code></pre> <p>Register the extension.</p> <p>Add an instance of our <code>AutoDocProcessor</code> to the Markdown parser.</p> <p>Parameters:</p> Source code in <code>src/mkdocstrings/_internal/extension.py</code> <pre><code>def extendMarkdown(self, md: Markdown) -&gt; None:  # noqa: N802 (casing: parent method's name)\n    \"\"\"Register the extension.\n\n    Add an instance of our [`AutoDocProcessor`][mkdocstrings.AutoDocProcessor] to the Markdown parser.\n\n    Arguments:\n        md: A `markdown.Markdown` instance.\n    \"\"\"\n    md.registerExtension(self)\n\n    # Zensical integration: get the current page from the Zensical-specific preprocessor.\n    if \"zensical_current_page\" in md.preprocessors:\n        self._autorefs.current_page = md.preprocessors[\"zensical_current_page\"]\n\n    md.parser.blockprocessors.register(\n        AutoDocProcessor(md, handlers=self._handlers, autorefs=self._autorefs),\n        \"mkdocstrings\",\n        priority=75,  # Right before markdown.blockprocessors.HashHeaderProcessor\n    )\n    md.treeprocessors.register(\n        _HeadingsPostProcessor(md),\n        \"mkdocstrings_post_headings\",\n        priority=4,  # Right after 'toc'.\n    )\n    md.treeprocessors.register(\n        _TocLabelsTreeProcessor(md),\n        \"mkdocstrings_post_toc_labels\",\n        priority=4,  # Right after 'toc'.\n    )\n\n    if self._autorefs_extension:\n        AutorefsExtension(self._autorefs).extendMarkdown(md)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsExtension.extendMarkdown(md)","level":4,"title":"<code>md</code>","text":"(<code>Markdown</code>)           –            <p>A <code>markdown.Markdown</code> instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsInnerExtension","level":2,"title":"MkdocstringsInnerExtension","text":"<pre><code>MkdocstringsInnerExtension(headings: list[Element])\n</code></pre> <p>               Bases: <code>Extension</code></p> <p>Extension that should always be added to Markdown sub-documents that handlers request (and only them).</p> <p>Parameters:</p> <p>Methods:</p> <ul> <li> <code>extendMarkdown</code>             –              <p>Register the extension.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>headings</code>           –            <p>The list that will be populated with all HTML heading elements encountered in the document.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def __init__(self, headings: list[Element]):\n    \"\"\"Initialize the object.\n\n    Arguments:\n        headings: A list that will be populated with all HTML heading elements encountered in the document.\n    \"\"\"\n    super().__init__()\n    self.headings = headings\n    \"\"\"The list that will be populated with all HTML heading elements encountered in the document.\"\"\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsInnerExtension(headings)","level":3,"title":"<code>headings</code>","text":"(<code>list[Element]</code>)           –            <p>A list that will be populated with all HTML heading elements encountered in the document.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsInnerExtension.headings","level":3,"title":"headings  <code>instance-attribute</code>","text":"<pre><code>headings = headings\n</code></pre> <p>The list that will be populated with all HTML heading elements encountered in the document.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsInnerExtension.extendMarkdown","level":3,"title":"extendMarkdown","text":"<pre><code>extendMarkdown(md: Markdown) -&gt; None\n</code></pre> <p>Register the extension.</p> <p>Parameters:</p> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def extendMarkdown(self, md: Markdown) -&gt; None:  # noqa: N802 (casing: parent method's name)\n    \"\"\"Register the extension.\n\n    Arguments:\n        md: A `markdown.Markdown` instance.\n    \"\"\"\n    md.registerExtension(self)\n    md.treeprocessors.register(\n        HeadingShiftingTreeprocessor(md, 0),\n        HeadingShiftingTreeprocessor.name,\n        priority=12,\n    )\n    md.treeprocessors.register(\n        IdPrependingTreeprocessor(md, \"\"),\n        IdPrependingTreeprocessor.name,\n        priority=4,  # Right after 'toc' (needed because that extension adds ids to headers).\n    )\n    md.treeprocessors.register(\n        _HeadingReportingTreeprocessor(md, self.headings),\n        _HeadingReportingTreeprocessor.name,\n        priority=1,  # Close to the end.\n    )\n    md.treeprocessors.register(\n        ParagraphStrippingTreeprocessor(md),\n        ParagraphStrippingTreeprocessor.name,\n        priority=0.99,  # Close to the end.\n    )\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsInnerExtension.extendMarkdown(md)","level":4,"title":"<code>md</code>","text":"(<code>Markdown</code>)           –            <p>A <code>markdown.Markdown</code> instance.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin","level":2,"title":"MkdocstringsPlugin","text":"<pre><code>MkdocstringsPlugin()\n</code></pre> <p>               Bases: <code>BasePlugin[PluginConfig]</code></p> <p>An <code>mkdocs</code> plugin.</p> <p>This plugin defines the following event hooks:</p> <ul> <li><code>on_config</code></li> <li><code>on_env</code></li> <li><code>on_post_build</code></li> </ul> <p>Check the Developing Plugins page of <code>mkdocs</code> for more information about its plugin system.</p> <p>Methods:</p> <ul> <li> <code>get_handler</code>             –              <p>Get a handler by its name. See mkdocstrings.Handlers.get_handler.</p> </li> <li> <code>on_config</code>             –              <p>Instantiate our Markdown extension.</p> </li> <li> <code>on_post_build</code>             –              <p>Teardown the handlers.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>css_filename</code>               (<code>str</code>)           –            <p>The path of the CSS file to write in the site directory.</p> </li> <li> <code>handlers</code>               (<code>Handlers</code>)           –            <p>Get the instance of mkdocstrings.Handlers for this plugin/build.</p> </li> <li> <code>inventory_enabled</code>               (<code>bool</code>)           –            <p>Tell if the inventory is enabled or not.</p> </li> <li> <code>on_env</code>           –            <p>Extra actions that need to happen after all Markdown-to-HTML page rendering.</p> </li> <li> <code>plugin_enabled</code>               (<code>bool</code>)           –            <p>Tell if the plugin is enabled or not.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/plugin.py</code> <pre><code>def __init__(self) -&gt; None:\n    \"\"\"Initialize the object.\"\"\"\n    super().__init__()\n    self._handlers: Handlers | None = None\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.css_filename","level":3,"title":"css_filename  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>css_filename: str = 'assets/_mkdocstrings.css'\n</code></pre> <p>The path of the CSS file to write in the site directory.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.handlers","level":3,"title":"handlers  <code>property</code>","text":"<pre><code>handlers: Handlers\n</code></pre> <p>Get the instance of mkdocstrings.Handlers for this plugin/build.</p> <p>Raises:</p> <ul> <li> <code>RuntimeError</code>             –            <p>If the plugin hasn't been initialized with a config.</p> </li> </ul> <p>Returns:</p> <ul> <li> <code>Handlers</code>           –            <p>An instance of mkdocstrings.Handlers (the same throughout the build).</p> </li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.inventory_enabled","level":3,"title":"inventory_enabled  <code>property</code>","text":"<pre><code>inventory_enabled: bool\n</code></pre> <p>Tell if the inventory is enabled or not.</p> <p>Returns:</p> <ul> <li> <code>bool</code>           –            <p>Whether the inventory is enabled.</p> </li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.on_env","level":3,"title":"on_env  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>on_env = CombinedEvent(\n    _on_env_load_inventories,\n    _on_env_add_css,\n    _on_env_write_inventory,\n    _on_env_apply_backlinks,\n)\n</code></pre> <p>Extra actions that need to happen after all Markdown-to-HTML page rendering.</p> <p>Hook for the <code>on_env</code> event.</p> <ul> <li>Gather results from background inventory download tasks.</li> <li>Write mkdocstrings' extra files (CSS, inventory) into the site directory.</li> <li>Apply backlinks to the HTML output of each page.</li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.plugin_enabled","level":3,"title":"plugin_enabled  <code>property</code>","text":"<pre><code>plugin_enabled: bool\n</code></pre> <p>Tell if the plugin is enabled or not.</p> <p>Returns:</p> <ul> <li> <code>bool</code>           –            <p>Whether the plugin is enabled.</p> </li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.get_handler","level":3,"title":"get_handler","text":"<pre><code>get_handler(handler_name: str) -&gt; BaseHandler\n</code></pre> <p>Get a handler by its name. See mkdocstrings.Handlers.get_handler.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>BaseHandler</code>           –            <p>An instance of a subclass of <code>BaseHandler</code>.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/plugin.py</code> <pre><code>def get_handler(self, handler_name: str) -&gt; BaseHandler:\n    \"\"\"Get a handler by its name. See [mkdocstrings.Handlers.get_handler][].\n\n    Arguments:\n        handler_name: The name of the handler.\n\n    Returns:\n        An instance of a subclass of [`BaseHandler`][mkdocstrings.BaseHandler].\n    \"\"\"\n    return self.handlers.get_handler(handler_name)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.get_handler(handler_name)","level":4,"title":"<code>handler_name</code>","text":"(<code>str</code>)           –            <p>The name of the handler.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.on_config","level":3,"title":"on_config","text":"<pre><code>on_config(config: MkDocsConfig) -&gt; MkDocsConfig | None\n</code></pre> <p>Instantiate our Markdown extension.</p> <p>Hook for the <code>on_config</code> event. In this hook, we instantiate our <code>MkdocstringsExtension</code> and add it to the list of Markdown extensions used by <code>mkdocs</code>.</p> <p>We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it later when processing markdown to get handlers and their global configurations).</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>MkDocsConfig | None</code>           –            <p>The modified config.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/plugin.py</code> <pre><code>def on_config(self, config: MkDocsConfig) -&gt; MkDocsConfig | None:\n    \"\"\"Instantiate our Markdown extension.\n\n    Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).\n    In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.MkdocstringsExtension]\n    and add it to the list of Markdown extensions used by `mkdocs`.\n\n    We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it\n    later when processing markdown to get handlers and their global configurations).\n\n    Arguments:\n        config: The MkDocs config object.\n\n    Returns:\n        The modified config.\n    \"\"\"\n    if not self.plugin_enabled:\n        _logger.debug(\"Plugin is not enabled. Skipping.\")\n        return config\n    _logger.debug(\"Adding extension to the list\")\n\n    locale = self.config.locale or config.theme.get(\"language\") or config.theme.get(\"locale\") or \"en\"\n    locale = str(locale).replace(\"_\", \"-\")\n\n    handlers = Handlers(\n        default=self.config.default_handler,\n        handlers_config=self.config.handlers,\n        theme=config.theme.name or os.path.dirname(config.theme.dirs[0]),  # noqa: PTH120\n        custom_templates=self.config.custom_templates,\n        mdx=config.markdown_extensions,\n        mdx_config=config.mdx_configs,\n        inventory_project=config.site_name,\n        inventory_version=\"0.0.0\",  # TODO: Find a way to get actual version.\n        locale=locale,\n        tool_config=config,\n    )\n\n    handlers._download_inventories()\n\n    AutorefsPlugin.record_backlinks = True\n    autorefs: AutorefsPlugin\n    try:\n        # If autorefs plugin is explicitly enabled, just use it.\n        autorefs = config.plugins[\"autorefs\"]  # ty: ignore[invalid-assignment]\n        _logger.debug(\"Picked up existing autorefs instance %r\", autorefs)\n    except KeyError:\n        # Otherwise, add a limited instance of it that acts only on what's added through `register_anchor`.\n        autorefs = AutorefsPlugin()\n        autorefs.config = AutorefsConfig()  # ty:ignore[invalid-assignment]\n        autorefs.scan_toc = False\n        config.plugins[\"autorefs\"] = autorefs\n        _logger.debug(\"Added a subdued autorefs instance %r\", autorefs)\n\n    mkdocstrings_extension = MkdocstringsExtension(handlers, autorefs)\n    config.markdown_extensions.append(mkdocstrings_extension)  # ty: ignore[invalid-argument-type]\n\n    config.extra_css.insert(0, self.css_filename)  # So that it has lower priority than user files.\n\n    self._autorefs = autorefs\n    self._handlers = handlers\n    return config\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.on_config(config)","level":4,"title":"<code>config</code>","text":"(<code>MkDocsConfig</code>)           –            <p>The MkDocs config object.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.on_post_build","level":3,"title":"on_post_build","text":"<pre><code>on_post_build(config: MkDocsConfig, **kwargs: Any) -&gt; None\n</code></pre> <p>Teardown the handlers.</p> <p>Hook for the <code>on_post_build</code> event. This hook is used to teardown all the handlers that were instantiated and cached during documentation buildup.</p> <p>For example, a handler could open a subprocess in the background and keep it open to feed it \"autodoc\" instructions and get back JSON data. If so, it should then close the subprocess at some point: the proper place to do this is in the handler's <code>teardown</code> method, which is indirectly called by this hook.</p> <p>Parameters:</p> Source code in <code>src/mkdocstrings/_internal/plugin.py</code> <pre><code>def on_post_build(\n    self,\n    config: MkDocsConfig,  # noqa: ARG002\n    **kwargs: Any,  # noqa: ARG002\n) -&gt; None:\n    \"\"\"Teardown the handlers.\n\n    Hook for the [`on_post_build` event](https://www.mkdocs.org/user-guide/plugins/#on_post_build).\n    This hook is used to teardown all the handlers that were instantiated and cached during documentation buildup.\n\n    For example, a handler could open a subprocess in the background and keep it open\n    to feed it \"autodoc\" instructions and get back JSON data. If so, it should then close the subprocess at some point:\n    the proper place to do this is in the handler's `teardown` method, which is indirectly called by this hook.\n\n    Arguments:\n        config: The MkDocs config object.\n        **kwargs: Additional arguments passed by MkDocs.\n    \"\"\"\n    if not self.plugin_enabled:\n        return\n\n    if self._handlers:\n        _logger.debug(\"Tearing handlers down\")\n        self.handlers.teardown()\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.on_post_build(config)","level":4,"title":"<code>config</code>","text":"(<code>MkDocsConfig</code>)           –            <p>The MkDocs config object.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.MkdocstringsPlugin.on_post_build(**kwargs)","level":4,"title":"<code>**kwargs</code>","text":"(<code>Any</code>, default:                   <code>{}</code> )           –            <p>Additional arguments passed by MkDocs.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.ParagraphStrippingTreeprocessor","level":2,"title":"ParagraphStrippingTreeprocessor","text":"<p>               Bases: <code>Treeprocessor</code></p> <p>Unwraps the <code>&lt;p&gt;</code> element around the whole output.</p> <p>Methods:</p> <ul> <li> <code>run</code>             –              <p>Unwrap the root element if it's a single <code>&lt;p&gt;</code> element.</p> </li> </ul> <p>Attributes:</p> <ul> <li> <code>name</code>               (<code>str</code>)           –            <p>The name of the treeprocessor.</p> </li> <li> <code>strip</code>               (<code>bool</code>)           –            <p>Whether to strip <code>&lt;p&gt;</code> elements or not.</p> </li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.ParagraphStrippingTreeprocessor.name","level":3,"title":"name  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>name: str = 'mkdocstrings_strip_paragraph'\n</code></pre> <p>The name of the treeprocessor.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.ParagraphStrippingTreeprocessor.strip","level":3,"title":"strip  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>strip: bool = False\n</code></pre> <p>Whether to strip <code>&lt;p&gt;</code> elements or not.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.ParagraphStrippingTreeprocessor.run","level":3,"title":"run","text":"<pre><code>run(root: Element) -&gt; Element | None\n</code></pre> <p>Unwrap the root element if it's a single <code>&lt;p&gt;</code> element.</p> Source code in <code>src/mkdocstrings/_internal/handlers/rendering.py</code> <pre><code>def run(self, root: Element) -&gt; Element | None:\n    \"\"\"Unwrap the root element if it's a single `&lt;p&gt;` element.\"\"\"\n    if self.strip and len(root) == 1 and root[0].tag == \"p\":\n        # Turn the single `&lt;p&gt;` element into the root element and inherit its tag name (it's significant!)\n        root[0].tag = root.tag\n        return root[0]\n    return None\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.PluginConfig","level":2,"title":"PluginConfig","text":"<p>               Bases: <code>Config</code></p> <p>The configuration options of <code>mkdocstrings</code>, written in <code>mkdocs.yml</code>.</p> <p>Attributes:</p> <ul> <li> <code>custom_templates</code>           –            <p>Location of custom templates to use when rendering API objects.</p> </li> <li> <code>default_handler</code>           –            <p>The default handler to use. The value is the name of the handler module. Default is \"python\".</p> </li> <li> <code>enable_inventory</code>           –            <p>Whether to enable object inventory creation.</p> </li> <li> <code>enabled</code>           –            <p>Whether to enable the plugin. Default is true. If false, mkdocstrings will not collect or render anything.</p> </li> <li> <code>handlers</code>           –            <p>Global configuration of handlers.</p> </li> <li> <code>locale</code>           –            <p>The locale to use for translations.</p> </li> </ul>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.PluginConfig.custom_templates","level":3,"title":"custom_templates  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>custom_templates = Optional(Dir(exists=True))\n</code></pre> <p>Location of custom templates to use when rendering API objects.</p> <p>Value should be the path of a directory relative to the MkDocs configuration file.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.PluginConfig.default_handler","level":3,"title":"default_handler  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>default_handler = Type(str, default='python')\n</code></pre> <p>The default handler to use. The value is the name of the handler module. Default is \"python\".</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.PluginConfig.enable_inventory","level":3,"title":"enable_inventory  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>enable_inventory = Optional(Type(bool))\n</code></pre> <p>Whether to enable object inventory creation.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.PluginConfig.enabled","level":3,"title":"enabled  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>enabled = Type(bool, default=True)\n</code></pre> <p>Whether to enable the plugin. Default is true. If false, mkdocstrings will not collect or render anything.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.PluginConfig.handlers","level":3,"title":"handlers  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>handlers = Type(dict, default={})\n</code></pre> <p>Global configuration of handlers.</p> <p>You can set global configuration per handler, applied everywhere, but overridable in each \"autodoc\" instruction. Example:</p> <pre><code>plugins:\n  - mkdocstrings:\n      handlers:\n        python:\n          options:\n            option1: true\n            option2: \"value\"\n        rust:\n          options:\n            option9: 2\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.PluginConfig.locale","level":3,"title":"locale  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>locale = Optional(Type(str))\n</code></pre> <p>The locale to use for translations.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.TemplateLogger","level":2,"title":"TemplateLogger","text":"<pre><code>TemplateLogger(logger: LoggerAdapter)\n</code></pre> <p>A wrapper class to allow logging in templates.</p> <p>The logging methods provided by this class all accept two parameters:</p> <ul> <li><code>msg</code>: The message to log.</li> <li><code>once</code>: If <code>True</code>, the message will only be logged once.</li> </ul> <p>Methods:</p> <ul> <li> <code>debug</code>             –              <p>Function to log a DEBUG message.</p> </li> <li> <code>info</code>             –              <p>Function to log an INFO message.</p> </li> <li> <code>warning</code>             –              <p>Function to log a WARNING message.</p> </li> <li> <code>error</code>             –              <p>Function to log an ERROR message.</p> </li> <li> <code>critical</code>             –              <p>Function to log a CRITICAL message.</p> </li> </ul> <p>Parameters:</p> <ul> <li> </li> </ul> <p>Attributes:</p> <ul> <li> <code>critical</code>           –            <p>Log a CRITICAL message.</p> </li> <li> <code>debug</code>           –            <p>Log a DEBUG message.</p> </li> <li> <code>error</code>           –            <p>Log an ERROR message.</p> </li> <li> <code>info</code>           –            <p>Log an INFO message.</p> </li> <li> <code>warning</code>           –            <p>Log a WARNING message.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/loggers.py</code> <pre><code>def __init__(self, logger: LoggerAdapter):\n    \"\"\"Initialize the object.\n\n    Arguments:\n        logger: A logger adapter.\n    \"\"\"\n    self.debug = get_template_logger_function(logger.debug)\n    \"\"\"Log a DEBUG message.\"\"\"\n    self.info = get_template_logger_function(logger.info)\n    \"\"\"Log an INFO message.\"\"\"\n    self.warning = get_template_logger_function(logger.warning)\n    \"\"\"Log a WARNING message.\"\"\"\n    self.error = get_template_logger_function(logger.error)\n    \"\"\"Log an ERROR message.\"\"\"\n    self.critical = get_template_logger_function(logger.critical)\n    \"\"\"Log a CRITICAL message.\"\"\"\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.TemplateLogger(logger)","level":3,"title":"<code>logger</code>","text":"(<code>LoggerAdapter</code>)           –            <p>A logger adapter.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.TemplateLogger.critical","level":3,"title":"critical  <code>instance-attribute</code>","text":"<pre><code>critical = get_template_logger_function(critical)\n</code></pre> <p>Log a CRITICAL message.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.TemplateLogger.debug","level":3,"title":"debug  <code>instance-attribute</code>","text":"<pre><code>debug = get_template_logger_function(debug)\n</code></pre> <p>Log a DEBUG message.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.TemplateLogger.error","level":3,"title":"error  <code>instance-attribute</code>","text":"<pre><code>error = get_template_logger_function(error)\n</code></pre> <p>Log an ERROR message.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.TemplateLogger.info","level":3,"title":"info  <code>instance-attribute</code>","text":"<pre><code>info = get_template_logger_function(info)\n</code></pre> <p>Log an INFO message.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.TemplateLogger.warning","level":3,"title":"warning  <code>instance-attribute</code>","text":"<pre><code>warning = get_template_logger_function(warning)\n</code></pre> <p>Log a WARNING message.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.ThemeNotSupported","level":2,"title":"ThemeNotSupported","text":"<p>               Bases: <code>Exception</code></p> <p>An exception raised to tell a theme is not supported.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.do_any","level":2,"title":"do_any","text":"<pre><code>do_any(seq: Sequence, attribute: str | None = None) -&gt; bool\n</code></pre> <p>Check if at least one of the item in the sequence evaluates to true.</p> <p>The <code>any</code> builtin as a filter for Jinja templates.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>bool</code>           –            <p>A boolean telling if any object of the iterable evaluated to True.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/handlers/base.py</code> <pre><code>def do_any(seq: Sequence, attribute: str | None = None) -&gt; bool:\n    \"\"\"Check if at least one of the item in the sequence evaluates to true.\n\n    The `any` builtin as a filter for Jinja templates.\n\n    Arguments:\n        seq: An iterable object.\n        attribute: The attribute name to use on each object of the iterable.\n\n    Returns:\n        A boolean telling if any object of the iterable evaluated to True.\n    \"\"\"\n    if attribute is None:\n        return any(seq)\n    return any(_[attribute] for _ in seq)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.do_any(seq)","level":3,"title":"<code>seq</code>","text":"(<code>Sequence</code>)           –            <p>An iterable object.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.do_any(attribute)","level":3,"title":"<code>attribute</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The attribute name to use on each object of the iterable.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.get_logger","level":2,"title":"get_logger","text":"<pre><code>get_logger(name: str) -&gt; LoggerAdapter\n</code></pre> <p>Return a pre-configured logger.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>LoggerAdapter</code>           –            <p>A logger configured to work well in MkDocs.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/loggers.py</code> <pre><code>def get_logger(name: str) -&gt; LoggerAdapter:\n    \"\"\"Return a pre-configured logger.\n\n    Arguments:\n        name: The name to use with `logging.getLogger`.\n\n    Returns:\n        A logger configured to work well in MkDocs.\n    \"\"\"\n    logger = logging.getLogger(f\"mkdocs.plugins.{name}\")\n    return LoggerAdapter(name.split(\".\", 1)[0], logger)\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.get_logger(name)","level":3,"title":"<code>name</code>","text":"(<code>str</code>)           –            <p>The name to use with <code>logging.getLogger</code>.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.get_template_logger","level":2,"title":"get_template_logger","text":"<pre><code>get_template_logger(\n    handler_name: str | None = None,\n) -&gt; TemplateLogger\n</code></pre> <p>Return a logger usable in templates.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>TemplateLogger</code>           –            <p>A template logger.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/loggers.py</code> <pre><code>def get_template_logger(handler_name: str | None = None) -&gt; TemplateLogger:\n    \"\"\"Return a logger usable in templates.\n\n    Parameters:\n        handler_name: The name of the handler.\n\n    Returns:\n        A template logger.\n    \"\"\"\n    handler_name = handler_name or \"base\"\n    return TemplateLogger(get_logger(f\"mkdocstrings_handlers.{handler_name}.templates\"))\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.get_template_logger(handler_name)","level":3,"title":"<code>handler_name</code>","text":"(<code>str | None</code>, default:                   <code>None</code> )           –            <p>The name of the handler.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.get_template_logger_function","level":2,"title":"get_template_logger_function","text":"<pre><code>get_template_logger_function(\n    logger_func: Callable,\n) -&gt; Callable\n</code></pre> <p>Create a wrapper function that automatically receives the Jinja template context.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>Callable</code>           –            <p>A function.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/loggers.py</code> <pre><code>def get_template_logger_function(logger_func: Callable) -&gt; Callable:\n    \"\"\"Create a wrapper function that automatically receives the Jinja template context.\n\n    Arguments:\n        logger_func: The logger function to use within the wrapper.\n\n    Returns:\n        A function.\n    \"\"\"\n\n    @pass_context\n    def wrapper(context: Context, msg: str | None = None, *args: Any, **kwargs: Any) -&gt; str:\n        \"\"\"Log a message.\n\n        Arguments:\n            context: The template context, automatically provided by Jinja.\n            msg: The message to log.\n            **kwargs: Additional arguments passed to the logger function.\n\n        Returns:\n            An empty string.\n        \"\"\"\n        logger_func(f\"%s: {msg or 'Rendering'}\", _Lazy(get_template_path, context), *args, **kwargs)\n        return \"\"\n\n    return wrapper\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.get_template_logger_function(logger_func)","level":3,"title":"<code>logger_func</code>","text":"(<code>Callable</code>)           –            <p>The logger function to use within the wrapper.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.get_template_path","level":2,"title":"get_template_path","text":"<pre><code>get_template_path(context: Context) -&gt; str\n</code></pre> <p>Return the path to the template currently using the given context.</p> <p>Parameters:</p> <p>Returns:</p> <ul> <li> <code>str</code>           –            <p>The relative path to the template.</p> </li> </ul> Source code in <code>src/mkdocstrings/_internal/loggers.py</code> <pre><code>def get_template_path(context: Context) -&gt; str:\n    \"\"\"Return the path to the template currently using the given context.\n\n    Arguments:\n        context: The template context.\n\n    Returns:\n        The relative path to the template.\n    \"\"\"\n    context_name: str = str(context.name)\n    filename = context.environment.get_template(context_name).filename\n    if filename:\n        for template_dir in TEMPLATES_DIRS:\n            with suppress(ValueError):\n                return str(Path(filename).relative_to(template_dir))\n        with suppress(ValueError):\n            return str(Path(filename).relative_to(Path.cwd()))\n        return filename\n    return context_name\n</code></pre>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.get_template_path(context)","level":3,"title":"<code>context</code>","text":"(<code>Context</code>)           –            <p>The template context.</p>","path":["API reference"],"tags":[]},{"location":"reference/api/#mkdocstrings.makeExtension","level":2,"title":"makeExtension","text":"<pre><code>makeExtension(\n    *,\n    default_handler: str | None = None,\n    inventory_project: str | None = None,\n    inventory_version: str | None = None,\n    handlers: dict[str, dict] | None = None,\n    custom_templates: str | None = None,\n    markdown_extensions: list[str | dict | Extension]\n    | None = None,\n    locale: str | None = None,\n    config_file_path: str | None = None,\n) -&gt; MkdocstringsExtension\n</code></pre> <p>Create the extension instance.</p> <p>We only support this function being used by Zensical. Consider this function private API.</p> Source code in <code>src/mkdocstrings/_internal/extension.py</code> <pre><code>def makeExtension(  # noqa: N802\n    *,\n    default_handler: str | None = None,\n    inventory_project: str | None = None,\n    inventory_version: str | None = None,\n    handlers: dict[str, dict] | None = None,\n    custom_templates: str | None = None,\n    markdown_extensions: list[str | dict | Extension] | None = None,\n    locale: str | None = None,\n    config_file_path: str | None = None,\n) -&gt; MkdocstringsExtension:\n    \"\"\"Create the extension instance.\n\n    We only support this function being used by Zensical.\n    Consider this function private API.\n    \"\"\"\n    global _AUTOREFS  # noqa: PLW0603\n    if _AUTOREFS is None:\n        _AUTOREFS = AutorefsPlugin()\n        _AUTOREFS.config = AutorefsConfig()  # ty:ignore[invalid-assignment]\n        _AUTOREFS.config.resolve_closest = True\n        _AUTOREFS.config.link_titles = \"auto\"\n        _AUTOREFS.config.strip_title_tags = \"auto\"\n        _AUTOREFS.scan_toc = True\n        _AUTOREFS._link_titles = \"external\"\n        _AUTOREFS._strip_title_tags = False\n\n    global _HANDLERS  # noqa: PLW0603\n    if _HANDLERS is None:\n        mdx, mdx_config = _split_configs(markdown_extensions or [])\n        tool_config = _ToolConfig(config_file_path=config_file_path)\n        mdx.append(AutorefsExtension(_AUTOREFS))\n        _HANDLERS = Handlers(\n            theme=\"material\",\n            default=default_handler or _default_config[\"default_handler\"],\n            inventory_project=inventory_project or \"Project\",\n            inventory_version=inventory_version or \"0.0.0\",\n            handlers_config=handlers or _default_config[\"handlers\"],\n            custom_templates=custom_templates or _default_config[\"custom_templates\"],\n            mdx=mdx,\n            mdx_config=mdx_config,\n            locale=locale or _default_config[\"locale\"],\n            tool_config=tool_config,\n        )\n\n        _HANDLERS._download_inventories()\n        register = _AUTOREFS.register_url\n        for identifier, url in _HANDLERS._yield_inventory_items():\n            register(identifier, url)\n\n    return MkdocstringsExtension(\n        handlers=_HANDLERS,\n        autorefs=_AUTOREFS,\n        autorefs_extension=True,\n    )\n</code></pre>","path":["API reference"],"tags":[]},{"location":"usage/","level":1,"title":"Usage","text":"","path":["Usage"],"tags":[]},{"location":"usage/#autodoc-syntax","level":2,"title":"Autodoc syntax","text":"<p>mkdocstrings works by processing special expressions in your Markdown files.</p> <p>The syntax is as follows:</p> <pre><code>::: identifier\n    YAML block\n</code></pre> <p>Resources on YAML</p> <p> YAML can sometimes be a bit tricky, particularly on indentation. Here are some resources that other users found useful to better understand YAML's peculiarities.</p> <ul> <li>YAML idiosyncrasies</li> <li>YAML multiline</li> </ul> <p>The <code>identifier</code> is a string identifying the object you want to document. The format of an identifier can vary from one handler to another. For example, the Python handler expects the full dotted-path to a Python object: <code>my_package.my_module.MyClass.my_method</code>.</p> <p>The YAML block is optional, and contains some configuration options:</p> <ul> <li><code>handler</code>: the name of the handler to use to collect and render this object.   By default, it will use the value defined in the Global options's   <code>default_handler</code> key, or <code>\"python\"</code>.</li> <li><code>options</code>: a dictionary of options passed to the handler's methods responsible both   for collecting and rendering the documentation. These options can be defined   globally (in <code>mkdocs.yml</code>, see Global options),   locally (as described here), or both.</li> </ul> <p>Example with the Python handler</p> docs/my_page.mdmkdocs.ymlsrc/my_package/my_module.pyResult <pre><code># Documentation for `MyClass`\n\n::: my_package.my_module.MyClass\n    handler: python\n    options:\n      members:\n        - method_a\n        - method_b\n      show_root_heading: false\n      show_source: false\n</code></pre> <pre><code>nav:\n  - \"My page\": my_page.md\n</code></pre> <pre><code>class MyClass:\n    \"\"\"Print print print!\"\"\"\n\n    def method_a(self):\n        \"\"\"Print A!\"\"\"\n        print(\"A!\")\n\n    def method_b(self):\n        \"\"\"Print B!\"\"\"\n        print(\"B!\")\n\n    def method_c(self):\n        \"\"\"Print C!\"\"\"\n        print(\"C!\")\n</code></pre> <p></p> <p>It is also possible to integrate a mkdocstrings identifier into a Markdown header:</p> <pre><code>## ::: my_package.my_module.MyClass\n    options:\n      show_source: false\n</code></pre> <p>The above is equivalent to:</p> <pre><code>::: my_package.my_module.MyClass\n    options:\n      show_source: false\n      heading_level: 2\n</code></pre>","path":["Usage"],"tags":[]},{"location":"usage/#documentation-for-myclass","level":3,"title":"Documentation for <code>MyClass</code>","text":"<p>Print print print!</p>","path":["Usage"],"tags":[]},{"location":"usage/#mkdocstrings.my_module.MyClass.method_a","level":4,"title":"<code> method_a(self) </code>","text":"<p>Print A!</p>","path":["Usage"],"tags":[]},{"location":"usage/#mkdocstrings.my_module.MyClass.method_b","level":4,"title":"<code> method_b(self) </code>","text":"<p>Print B!</p>","path":["Usage"],"tags":[]},{"location":"usage/#global-options","level":2,"title":"Global options","text":"<p>mkdocstrings accepts a few top-level configuration options in <code>mkdocs.yml</code>:</p> <ul> <li><code>default_handler</code>: The handler that is used by default when no handler is specified.</li> <li><code>custom_templates</code>: The path to a directory containing custom templates.   The path is relative to the MkDocs configuration file.   See Theming.</li> <li><code>handlers</code>: The handlers' global configuration.</li> <li><code>enable_inventory</code>: Whether to enable inventory file generation.   See Cross-references to other projects / inventories</li> <li><code>locale</code>: The locale used for translations. See Internationalization.</li> <li><code>enabled</code> (New in version 0.20): Whether to enable the plugin. Defaults to <code>true</code>.   Can be used to reduce build times when doing local development.   Especially useful when used with environment variables (see example below).</li> </ul> <p>Example</p> mkdocs.yml<pre><code>plugins:\n- mkdocstrings:\n    enabled: !ENV [ENABLE_MKDOCSTRINGS, true]\n    custom_templates: templates\n    default_handler: python\n    locale: en\n    handlers:\n      python:\n        options:\n          show_source: false\n</code></pre> <p>The handlers global configuration can then be overridden by local configurations:</p> docs/some_page.md<pre><code>::: my_package.my_module.MyClass\n    options:\n      show_source: true\n</code></pre> <p>Some handlers accept additional global configuration. Check the documentation for your handler of interest in Handlers.</p>","path":["Usage"],"tags":[]},{"location":"usage/#internationalization-i18n","level":2,"title":"Internationalization (I18N)","text":"<p>Some handlers support multiple languages.</p> <p>If the handler supports localization, the locale it uses is determined by the following order of precedence:</p> <ul> <li><code>locale</code> in global options</li> <li><code>theme.language</code>: used by the MkDocs Material theme</li> <li><code>theme.locale</code> in MkDocs configuration</li> </ul>","path":["Usage"],"tags":[]},{"location":"usage/#cross-references","level":2,"title":"Cross-references","text":"<p>Cross-references are written as Markdown reference-style links:</p> MarkdownHTML Result <pre><code>With a custom title:\n[`Object 1`][full.path.object1]\n\nWith the identifier as title:\n[full.path.object2][]\n</code></pre> <pre><code>&lt;p&gt;With a custom title:\n&lt;a href=\"https://example.com/page1#full.path.object1\"&gt;&lt;code&gt;Object 1&lt;/code&gt;&lt;/a&gt;&lt;p&gt;\n&lt;p&gt;With the identifier as title:\n&lt;a href=\"https://example.com/page2#full.path.object2\"&gt;full.path.object2&lt;/a&gt;&lt;/p&gt;\n</code></pre> <p>Any item that was inserted using the autodoc syntax (e.g. <code>full.path.object1</code>) is possible to link to by using the same identifier with the cross-reference syntax (<code>[example][full.path.object1]</code>). But the cross-references are also applicable to the items' children that get pulled in.</p>","path":["Usage"],"tags":[]},{"location":"usage/#finding-out-the-anchor","level":3,"title":"Finding out the anchor","text":"<p>If you're not sure which exact identifier a doc item uses, you can look at its \"anchor\", which your Web browser will show in the URL bar when clicking an item's entry in the table of contents. If the URL is <code>https://example.com/some/page.html#full.path.object1</code> then you know that this item is possible to link to with <code>[example][full.path.object1]</code>, regardless of the current page.</p>","path":["Usage"],"tags":[]},{"location":"usage/#cross-references-to-any-markdown-heading","level":3,"title":"Cross-references to any Markdown heading","text":"<p>Changed in version 0.15</p> <p> Linking to any Markdown heading used to be the default, but now opt-in is required.</p> <p>If you want to link to any Markdown heading, not just mkdocstrings-inserted items, please enable the autorefs plugin for MkDocs by adding <code>autorefs</code> to <code>plugins</code>:</p> mkdocs.yml<pre><code>plugins:\n- search\n- autorefs\n- mkdocstrings:\n    [...]\n</code></pre> <p>Note that you don't need to (<code>pip</code>) install anything more; this plugin is guaranteed to be pulled in with mkdocstrings.</p> <p>Example</p> doc1.mddoc2.mdResult HTML for doc2 <pre><code>## Hello, world!\n\nTesting\n</code></pre> <pre><code>## Something else\n\nPlease see the [Hello, World!][hello-world] section.\n</code></pre> <pre><code>&lt;p&gt;Please see the &lt;a href=\"doc1.html#hello-world\"&gt;Hello, World!&lt;/a&gt; section.&lt;/p&gt;\n</code></pre>","path":["Usage"],"tags":[]},{"location":"usage/#cross-references-to-a-sub-heading-in-a-docstring","level":3,"title":"Cross-references to a sub-heading in a docstring","text":"<p>New in version 0.14</p> <p>If you have a Markdown heading inside your docstring, you can also link directly to it. In the example below you see the identifier to be linked is <code>foo.bar--tips</code>, because it's the \"Tips\" heading that's part of the <code>foo.bar</code> object, joined with \"<code>--</code>\".</p> <p>Example</p> foo.pydoc1.mddoc2.mdHTML result for doc2 <pre><code>def bar():\n    \"\"\"Hello, world!\n\n    # Tips\n\n    - Stay hydrated.\n    \"\"\"\n</code></pre> <pre><code>::: foo.bar\n</code></pre> <pre><code>Check out the [tips][foo.bar--tips]\n</code></pre> <pre><code>&lt;p&gt;Check out the &lt;a href=\"doc1.html#foo.bar--tips\"&gt;tips&lt;/a&gt;&lt;/p&gt;\n</code></pre> <p>The above tip about Finding out the anchor also applies the same way here.</p> <p>You may also notice that such a heading does not get rendered as a <code>&lt;h1&gt;</code> element directly, but rather the level gets shifted to fit the encompassing document structure. If you're curious about the implementation, check out mkdocstrings.HeadingShiftingTreeprocessor and others.</p>","path":["Usage"],"tags":[]},{"location":"usage/#cross-references-to-other-projects-inventories","level":3,"title":"Cross-references to other projects / inventories","text":"<p>New in version 0.16</p> <p>Python developers coming from Sphinx might know about its <code>intersphinx</code> extension, that allows to cross-reference items between several projects. mkdocstrings has a similar feature.</p> <p>To reference an item from another project, you must first tell mkdocstrings to load the inventory it provides. Each handler will be responsible of loading inventories specific to its language. For example, the Python handler can load Sphinx-generated inventories (<code>objects.inv</code>).</p> <p>In the following snippet, we load the inventory provided by <code>installer</code>:</p> mkdocs.yml<pre><code>plugins:\n- mkdocstrings:\n    handlers:\n      python:\n        inventories:\n        - https://installer.readthedocs.io/en/stable/objects.inv\n</code></pre> <p>Now it is possible to cross-reference <code>installer</code>'s items. For example:</p> MarkdownResult (HTML)Result (displayed) <pre><code>See [installer.records][] to learn about records.\n</code></pre> <pre><code>&lt;p&gt;See &lt;a href=\"https://installer.readthedocs.io/en/stable/api/records/#module-installer.records\"&gt;installer.records&lt;/a&gt;\nto learn about records.&lt;/p&gt;\n</code></pre> <p>See installer.records to learn about records.</p> <p>You can of course select another version of the inventory, for example:</p> <pre><code>plugins:\n- mkdocstrings:\n    handlers:\n      python:\n        inventories:\n        # latest instead of stable\n        - https://installer.readthedocs.io/en/latest/objects.inv\n</code></pre> <p>In case the inventory file is not served under the base documentation URL, you can explicitly specify both URLs:</p> <pre><code>plugins:\n- mkdocstrings:\n    handlers:\n      python:\n        inventories:\n        - url: https://cdn.example.com/version/objects.inv\n          base_url: https://docs.example.com/version\n</code></pre> <p>Absolute URLs to cross-referenced items will then be based on <code>https://docs.example.com/version/</code> instead of <code>https://cdn.example.com/version/</code>.</p> <p>If you need authentication to access the inventory file, you can provide the credentials in the URL, either as <code>username:password</code>:</p> <pre><code>- url: https://username:password@private.example.com/version/objects.inv\n</code></pre> <p>...or with token authentication:</p> <pre><code>- url: https://token123@private.example.com/version/objects.inv\n</code></pre> <p>The credentials can also be specified using environment variables in the form <code>${ENV_VAR}</code>:</p> <pre><code>- url: https://${USERNAME}:${PASSWORD}@private.example.com/version/objects.inv\n</code></pre> <p>Reciprocally, mkdocstrings also allows to generate an inventory file in the Sphinx format. It will be enabled by default if the Python handler is used, and generated as <code>objects.inv</code> in the final site directory. Other projects will be able to cross-reference items from your project.</p> <p>To explicitly enable or disable the generation of the inventory file, use the global <code>enable_inventory</code> option:</p> <pre><code>plugins:\n- mkdocstrings:\n    enable_inventory: false\n</code></pre>","path":["Usage"],"tags":[]},{"location":"usage/handlers/","level":1,"title":"Handlers","text":"<p>A handler is what makes it possible to collect and render documentation for a particular language.</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#available-handlers","level":2,"title":"Available handlers","text":"<ul> <li>C</li> <li>Crystal</li> <li>GitHub Actions</li> <li>Python</li> <li>Python (Legacy)</li> <li>MATLAB</li> <li>Shell</li> <li>TypeScript</li> <li>VBA</li> </ul>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#about-the-python-handlers","level":2,"title":"About the Python handlers","text":"<p>Since version 0.18, a new Python handler is available. It is based on Griffe, which is an improved version of pytkdocs.</p> <p>If you want to keep using the legacy handler as long as possible, you can depend on <code>mkdocstrings-python-legacy</code> directly, or specify the <code>python-legacy</code> extra when depending on mkdocstrings:</p> pyproject.toml<pre><code># PEP 621 dependencies declaration\n# adapt to your dependencies manager\n[project]\ndependencies = [\n    \"mkdocstrings[python-legacy]&gt;=0.18\",\n]\n</code></pre> <p>The legacy handler will continue to \"work\" for many releases, as long as the new handler does not cover all previous use-cases.</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#migrate-to-the-new-python-handler","level":3,"title":"Migrate to the new Python handler","text":"<p>To use the new Python handler, you can depend on <code>mkdocstrings-python</code> directly, or specify the <code>python</code> extra when depending on mkdocstrings:</p> pyproject.toml<pre><code># PEP 621 dependencies declaration\n# adapt to your dependencies manager\n[project]\ndependencies = [\n    \"mkdocstrings[python]&gt;=0.18\",\n]\n</code></pre>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#selection-options","level":4,"title":"Selection options","text":"<p>Warning</p> <p>Since mkdocstrings 0.19, the YAML <code>selection</code> key is merged into the <code>options</code> key.</p> <ul> <li> <code>filters</code> is implemented, and used as before.</li> <li> <code>members</code> is implemented, and used as before.</li> <li> <code>inherited_members</code> is implemented.</li> <li> <code>docstring_style</code> is implemented, and used as before,   except for the <code>restructured-text</code> style which is renamed <code>sphinx</code>.   Numpy-style is now built-in, so you can stop depending on <code>pytkdocs[numpy-style]</code>   or <code>docstring_parser</code>.</li> <li> <code>docstring_options</code> is implemented, and used as before.   Refer to the <code>griffe</code> documentation   for the updated list of supported docstring options.</li> <li> <code>new_path_syntax</code> is irrelevant now. If you were setting it to True,   remove the option and replace every colon (<code>:</code>) in your autodoc identifiers   by dots (<code>.</code>).</li> </ul> <p>See all the handler's options.</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#rendering-options","level":4,"title":"Rendering options","text":"<p>Warning</p> <p>Since mkdocstrings 0.19, the YAML <code>rendering</code> key is merged into the <code>options</code> key.</p> <p>Every previous option is supported. Additional options are available:</p> <ul> <li> <code>separate_signature</code>: Render the signature (or attribute value) in a code block below the heading,   instead as inline code. Useful for long signatures. If Black is installed,   the signature is formatted. Default: <code>False</code>.</li> <li> <code>line_length</code>: The maximum line length to use when formatting signatures. Default: <code>60</code>.</li> <li> <code>show_submodules</code>: Whether to render submodules of a module when iterating on children.   Default: <code>False</code>.</li> <li> <code>docstring_section_style</code>: The style to use to render docstring sections such as attributes,   parameters, etc. Available styles: <code>\"table\"</code> (default), <code>\"list\"</code> and <code>\"spacy\"</code>. The SpaCy style   is a poor implementation of their table style.   We are open to improvements through PRs!</li> </ul> <p>See all the handler's options.</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#templates","level":4,"title":"Templates","text":"<p>Templates are mostly the same as before, but the file layout has changed, as well as some file names. See the documentation about the Python handler templates.</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#custom-handlers","level":2,"title":"Custom handlers","text":"<p>Since version 0.14, you can create and use custom handlers thanks to namespace packages. For more information about namespace packages, see their documentation.</p> <p>TL;DR - Project template for handlers</p> <p> mkdocstrings provides a Copier template to kickstart new handlers: https://github.com/mkdocstrings/handler-template. To use it, install Copier (<code>pipx install copier</code>), then run <code>copier gh:mkdocstrings/handler-template my_handler</code> to generate a new project. See its upstream documentation to learn how to work on the generated project.</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#packaging","level":3,"title":"Packaging","text":"<p>For mkdocstrings, a custom handler package would have the following structure:</p> <pre><code>📁 your_repository\n└─╴📁 mkdocstrings_handlers\n   └─╴📁 custom_handler\n      ├─╴📁 templates\n      │  ├─╴📁 material\n      │  ├─╴📁 mkdocs\n      │  └─╴📁 readthedocs\n      └─╴📄 __init__.py\n</code></pre> <p>Note the absence of <code>__init__.py</code> module in <code>mkdocstrings_handlers</code>!</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#code","level":3,"title":"Code","text":"<p>A handler is a subclass of the base handler provided by mkdocstrings. See the documentation for the <code>BaseHandler</code>.</p> <p>Subclasses of the base handler must declare a <code>name</code> and <code>domain</code> as class attributes, as well as implement the following methods:</p> <ul> <li><code>collect(identifier, options)</code> (required): method responsible for collecting and returning data (extracting   documentation from source code, loading introspecting objects in memory, other sources? etc.)</li> <li><code>render(identifier, options)</code> (required): method responsible for actually rendering the data to HTML,   using the Jinja templates provided by your package.</li> <li><code>get_options(local_options)</code> (required): method responsible for combining global options with local ones.</li> <li><code>get_aliases(identifier)</code> (recommended): method responsible for returning known aliases of object identifiers,   in order to register cross-references in the autorefs plugin.</li> <li><code>get_inventory_urls()</code> (optional): method responsible for returning a list of URLs to download (object inventories)   along with configuration options (for loading the inventory with <code>load_inventory</code>).</li> <li><code>load_inventory(in_file, url, **options)</code> (optional): method responsible for loading an inventory (binary file-handle)   and yielding tuples of identifiers and URLs.</li> <li><code>update_env(config)</code> (optional): Gives you a chance to customize the Jinja environment used to render templates,   for examples by adding/removing Jinja filters and global context variables.</li> <li><code>teardown()</code> (optional): Clean up / teardown anything that needs it at the end of the build.</li> </ul> <p>You must implement a <code>get_handler</code> method at the module level, which returns an instance of your handler. This function takes the following parameters:</p> <ul> <li><code>theme</code> (string, theme name)</li> <li><code>custom_templates</code> (optional string, path to custom templates directory)</li> <li><code>mdx</code> (list, Markdown extensions)</li> <li><code>mdx_config</code> (dict, extensions configuration)</li> <li><code>handler_config</code> (dict, handle configuration)</li> <li><code>tool_config</code> (dict, the whole MkDocs configuration)</li> </ul> <p>These arguments are all passed as keyword arguments, so you can ignore them by adding <code>**kwargs</code> or similar to your signature.</p> <p>You should not modify the MkDocs config but can use it to get information about the MkDocs instance such as where the current <code>site_dir</code> lives. See the Mkdocs Configuration for more info about what is accessible from it.</p> <p>Check out how the Python handler is written for inspiration.</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#templates_1","level":3,"title":"Templates","text":"<p>Your handler's implementation should normally be backed by templates, which go to the directory <code>mkdocstrings_handlers/custom_handler/templates/some_theme</code> (<code>custom_handler</code> here should be replaced with the actual name of your handler, and <code>some_theme</code> should be the name of an actual MkDocs theme that you support, e.g. <code>material</code>).</p> <p>With that structure, you can use <code>self.env.get_template(\"foo.html\")</code> inside your <code>render</code> method. This already chooses the subdirectory based on the current MkDocs theme.</p> <p>If you wish to support any MkDocs theme, rather than a few specifically selected ones, you can pick one theme's subdirectory to be the fallback for when an unknown theme is encountered. Then you just need to set the <code>fallback_theme</code> variable on your handler subclass. The fallback directory can be used even for themes you explicitly support: you can omit some template from one of the other theme directories in case they're exactly the same as in the fallback theme.</p> <p>If your theme's HTML requires CSS to go along with it, put it into a file named <code>mkdocstrings_handlers/custom_handler/templates/some_theme/style.css</code>, then this will be included into the final site automatically if this handler is ever used. Alternatively, you can put the CSS as a string into the <code>extra_css</code> variable of your handler.</p> <p>Finally, it's possible to entirely omit templates, and tell mkdocstrings to use the templates of another handler. In you handler, override the <code>get_templates_dir()</code> method to return the other handlers templates path:</p> <pre><code>from pathlib import Path\nfrom mkdocstrings import BaseHandler\n\n\nclass CobraHandler(BaseHandler):\n    def get_templates_dir(self, handler: str | None = None) -&gt; Path:\n        # use the python handler templates\n        # (it assumes the python handler is installed)\n        return super().get_templates_dir(\"python\")\n</code></pre>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#usage","level":3,"title":"Usage","text":"<p>When a custom handler is installed, it is then available to mkdocstrings. You can configure it as usual:</p> mkdocs.yml<pre><code>plugins:\n- mkdocstrings:\n    handlers:\n      custom_handler:\n        handler_config_option: yes\n        options:\n          some_config_option: \"a\"\n          other_config_option: 0\n</code></pre> <p>...and use it in your autodoc instructions:</p> docs/some_page.md<pre><code># Documentation for an object\n\n::: some.objects.path\n    handler: custom_handler\n    options:\n      some_config_option: \"b\"\n      other_config_option: 1\n</code></pre>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/handlers/#handler-extensions","level":2,"title":"Handler extensions","text":"<p>mkdocstrings provides a way for third-party packages to extend or alter the behavior of handlers. For example, an extension of the Python handler could add specific support for another Python library.</p> <p>Note</p> <p>This feature is intended for developers. If you are a user and want to customize how objects are rendered, see Theming / Customization.</p> <p>Such extensions can register additional template folders that will be used when rendering collected data. Extensions are responsible for synchronizing with the handler itself so that it uses the additional templates.</p> <p>An extension is a Python package that defines an entry-point for a specific handler:</p> pyproject.toml<pre><code>[project.entry-points.\"mkdocstrings.python.templates\"] # (1)!\nextension-name = \"extension_package:get_templates_path\" # (2)!\n</code></pre> <ol> <li>Replace <code>python</code> by the name of the handler you want to add templates to.</li> <li>Replace <code>extension-name</code> by any name you want,     and replace <code>extension_package:get_templates_path</code>     by the actual module path and function name in your package.</li> </ol> <p>This entry-point assumes that the extension provides a <code>get_templates_path</code> function directly under the <code>extension_package</code> package:</p> <pre><code>pyproject.toml\nextension_package/\n    __init__.py\n    templates/\n</code></pre> extension_package/__init__.py<pre><code>from pathlib import Path\n\n\ndef get_templates_path() -&gt; Path:\n    return Path(__file__).parent / \"templates\"\n</code></pre> <p>This function doesn't accept any argument and returns the path (<code>pathlib.Path</code> or <code>str</code>) to a directory containing templates. The directory must contain one subfolder for each supported theme, even if empty (see \"fallback theme\" in custom handlers templates). For example:</p> <pre><code>pyproject.toml\nextension_package/\n    __init__.py\n    templates/\n        material/\n        readthedocs/\n        mkdocs/\n</code></pre> <p>mkdocstrings will add the folders corresponding to the user-selected theme, and to the handler's defined fallback theme, as usual.</p> <p>The names of the extension templates must not overlap with the handler's original templates.</p> <p>The extension is then responsible, in collaboration with its target handler, for mutating the collected data in order to instruct the handler to use one of the extension template when rendering particular objects. See each handler's docs to see if they support extensions, and how.</p>","path":["Usage","Handlers"],"tags":[]},{"location":"usage/theming/","level":1,"title":"Themes","text":"<p>mkdocstrings can support multiple MkDocs themes. It currently supports the Material for MkDocs theme and, partially, the built-in MkDocs and ReadTheDocs themes.</p> <p>Each handler can fallback to a particular theme when the user selected theme is not supported. For example, the Python handler will fallback to the Material for MkDocs templates.</p>","path":["Usage","Themes"],"tags":[]},{"location":"usage/theming/#customization","level":2,"title":"Customization","text":"<p>There is some degree of customization possible in mkdocstrings. First, you can write custom templates to override the theme templates. Second, the provided templates make use of CSS classes, so you can tweak the look and feel with extra CSS rules.</p>","path":["Usage","Themes"],"tags":[]},{"location":"usage/theming/#templates","level":3,"title":"Templates","text":"<p>To use custom templates and override the theme ones, specify the relative path from your configuration file to your templates directory with the <code>custom_templates</code> global configuration option:</p> mkdocs.yml<pre><code>plugins:\n- mkdocstrings:\n    custom_templates: templates\n</code></pre> <p>Your directory structure must be identical to the provided templates one:</p> <pre><code>📁 templates/\n├─╴📁 &lt;HANDLER 1&gt;/\n│   ├── 📁 &lt;THEME 1&gt;/\n│   └── 📁 &lt;THEME 2&gt;/\n└── 📁 &lt;HANDLER 2&gt;/\n    ├── 📁 &lt;THEME 1&gt;/\n    └── 📁 &lt;THEME 2&gt;/\n</code></pre> <p>For example, check out the Python template tree on GitHub.</p> <p>You don't have to replicate the whole tree, only the handlers, themes or templates you want to override. For example, to override some templates of the Material theme for Python:</p> <pre><code>📁 templates/\n└── 📁 python/\n    └── 📁 material/\n        ├── 📄 parameters.html\n        └── 📄 exceptions.html\n</code></pre> <p>In the HTML files, replace the original contents with your modified version. In the future, the templates will use Jinja blocks, so it will be easier to modify small part of the templates without copy-pasting the whole files.</p> <p>See the documentation about templates for:</p> <ul> <li>the Crystal handler: https://mkdocstrings.github.io/crystal/styling.html</li> <li>the Python handler: https://mkdocstrings.github.io/python/usage/customization/#templates</li> </ul>","path":["Usage","Themes"],"tags":[]},{"location":"usage/theming/#debugging","level":4,"title":"Debugging","text":"<p>Every template has access to a <code>log</code> function, allowing to log messages as usual:</p> <pre><code>{{ log.debug(\"A DEBUG message.\") }}\n{{ log.info(\"An INFO message.\") }}\n{{ log.warning(\"A WARNING message.\") }}\n{{ log.error(\"An ERROR message.\") }}\n{{ log.critical(\"A CRITICAL message.\") }}\n</code></pre>","path":["Usage","Themes"],"tags":[]},{"location":"usage/theming/#css-classes","level":3,"title":"CSS classes","text":"<p>Since each handler provides its own set of templates, with their own CSS classes, we cannot list them all here. See the documentation about CSS classes for:</p> <ul> <li>the Crystal handler: https://mkdocstrings.github.io/crystal/styling.html#custom-styles</li> <li>the Python handler: https://mkdocstrings.github.io/python/usage/customization/#css-classes</li> </ul>","path":["Usage","Themes"],"tags":[]},{"location":"usage/theming/#syntax-highlighting","level":3,"title":"Syntax highlighting","text":"<p>Code blocks that occur in the docstring of an item inserted with mkdocstrings, as well as code blocks (such as Source code) that mkdocstrings inserts itself, are syntax-highlighted according to the same rules as other normal code blocks in your document. See more details in mkdocstrings.Highlighter.</p> <p>As for the CSS class used for code blocks -- it will also match the \"normal\" config, so the default (<code>.codehilite</code> or <code>.highlight</code>) will match your chosen Markdown extension for highlighting.</p> <p>Changed in version 0.15</p> <p> The CSS class used to always be <code>.highlight</code>, but now it depends on the configuration.</p> <p>Long story short, you probably should add <code>pymdownx.highlight</code> to your <code>markdown_extensions</code>, and then use <code>.doc-contents .highlight</code> as the CSS selector in case you want to change something about mkdocstrings' code blocks specifically.</p>","path":["Usage","Themes"],"tags":[]}]}