Changelog¤

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

0.28.0 - 2025-02-03¤

Breaking Changes¤

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.

mkdocstrings.extension.AutoDocProcessor.__init__(parser): Parameter was removed
mkdocstrings.extension.AutoDocProcessor.__init__(md): Positional parameter was moved
mkdocstrings.extension.AutoDocProcessor.__init__(config): Parameter was removed
mkdocstrings.extension.AutoDocProcessor.__init__(handlers): Parameter kind was changed: positional or keyword -> keyword-only
mkdocstrings.extension.AutoDocProcessor.__init__(autorefs): Parameter kind was changed: positional or keyword -> keyword-only
mkdocstrings.extension.MkdocstringsExtension.__init__(config): Parameter was removed
mkdocstrings.extension.MkdocstringsExtension.__init__(handlers): Positional parameter was moved
mkdocstrings.extension.MkdocstringsExtension.__init__(autorefs): Positional parameter was moved
mkdocstrings.handlers.base.Handlers.__init__(config): Parameter was removed
mkdocstrings.handlers.base.Handlers.__init__(theme): Parameter was added as required
mkdocstrings.handlers.base.Handlers.__init__(default): Parameter was added as required
mkdocstrings.handlers.base.Handlers.__init__(inventory_project): Parameter was added as required
mkdocstrings.handlers.base.Handlers.__init__(tool_config): Parameter was added as required

Similarly, the following parameters were renamed, but the methods are only called from our own code, using positional arguments.

mkdocstrings.handlers.base.BaseHandler.collect(config): Parameter was renamed options
mkdocstrings.handlers.base.BaseHandler.render(config): Parameter was renamed options

Finally, the following method was removed, but this is again taken into account in our own code:

mkdocstrings.handlers.base.BaseHandler.get_anchors: Public object was removed

For these reasons, and because we're still in v0, we do not bump to v1 yet. See following deprecations.

Deprecations¤

mkdocstrings 0.28 will start emitting these deprecations warnings:

The handler argument is deprecated. The handler name must be specified as a class attribute.

Previously, the get_handler function would pass a handler (name) argument to the handler constructor. This name must now be set on the handler's class directly.

class MyHandler:
    name = "myhandler"

The domain attribute must be specified as a class attribute.

The domain class attribute on handlers is now mandatory and cannot be an empty string.

class MyHandler:
    domain = "mh"

The theme argument must be passed as a keyword argument.

This argument could previously be passed as a positional argument (from the get_handler function), and must now be passed as a keyword argument.

The custom_templates argument must be passed as a keyword argument.

Same as for theme, but with custom_templates.

The mdx argument must be provided (as a keyword argument).

The get_handler function now receives a mdx argument, which it must forward to the handler constructor and then to the base handler, either explicitly or through **kwargs:

ExplicitlyThrough **kwargs

def get_handler(..., mdx, ...):
    return MyHandler(..., mdx=mdx, ...)


class MyHandler:
    def __init__(self, ..., mdx, ...):
        super().__init__(..., mdx=mdx, ...)

def get_handler(..., **kwargs):
    return MyHandler(..., **kwargs)


class MyHandler:
    def __init__(self, ..., **kwargs):
        super().__init__(**kwargs)

In the meantime we still retrieve this mdx value at a different moment, by reading it from the MkDocs configuration.

The mdx_config argument must be provided (as a keyword argument).

Same as for mdx, but with mdx_config.

mkdocstrings v1 will stop handling 'import' in handlers configuration. Instead your handler must define a get_inventory_urls method that returns a list of URLs to download.

Previously, mkdocstrings would pop the import key from a handler's configuration to download each item (URLs). Items could be strings, or dictionaries with a url key. Now mkdocstrings gives back control to handlers, which must store this inventory configuration within them, and expose it again through a get_inventory_urls method. This method returns a list of tuples: an URL, and a dictionary of options that will be passed again to their load_inventory method. Handlers have now full control over the "inventory" setting.

from copy import deepcopy


def get_handler(..., handler_config, ...):
    return MyHandler(..., config=handler_config, ...)


class MyHandler:
    def __init__(self, ..., config, ...):
        self.config = config

    def get_inventory_urls(self):
        config = deepcopy(self.config["import"])
        return [(inv, {}) if isinstance(inv, str) else (inv.pop("url"), inv) for inv in config]

Changing the name of the key (for example from import to inventories) involves a change in user configuration, and both keys will have to be supported by your handler for some time.

def get_handler(..., handler_config, ...):
    if "inventories" not in handler_config and "import" in handler_config:
        warn("The 'import' key is renamed 'inventories'", FutureWarning)
        handler_config["inventories"] = handler_config.pop("import")
    return MyHandler(..., config=handler_config, ...)

Setting a fallback anchor function is deprecated and will be removed in a future release.

This comes from mkdocstrings and mkdocs-autorefs, and will disappear with mkdocstrings v0.28.

mkdocstrings v1 will start using your handler's get_options method to build options instead of merging the global and local options (dictionaries).

Handlers must now store their own global options (in an instance attribute), and implement a get_options method that receives local_options (a dict) and returns combined options (dict or custom object). These combined options are then passed to collect and render, so that these methods can use them right away.

def get_handler(..., handler_config, ...):
    return MyHandler(..., config=handler_config, ...)


class MyHandler:
    def __init__(self, ..., config, ...):
        self.config = config

    def get_options(local_options):
        return {**self.default_options, **self.config["options"], **local_options}

The update_env(md) parameter is deprecated. Use self.md instead.

Handlers can remove the md parameter from their update_env method implementation, and use self.md instead, if they need it.

No need to call super().update_env() anymore.

Handlers don't have to call the parent update_env method from their own implementation anymore, and can just drop the call.

The get_anchors method is deprecated. Declare a get_aliases method instead, accepting a string (identifier) instead of a collected object.

Previously, handlers would implement a get_anchors method that received a data object (typed CollectorItem) to return aliases for this object. This forced mkdocstrings to collect this object through the handler's collect method, which then required some logic with "fallback config" as to prevent unwanted collection. mkdocstrings gives back control to handlers and now calls get_aliases instead, which accepts an identifier (string) and lets the handler decide how to return aliases for this identifier. For example, it can replicate previous behavior by calling its own collect method with its own "fallback config", or do something different (cache lookup, etc.).

class MyHandler:
    def get_aliases(identifier):
        try:
            obj = self.collect(identifier, self.fallback_config)
            # or obj = self._objects_cache[identifier]
        except CollectionError:  # or KeyError
            return ()
        return ...  # previous logic in `get_anchors`

The config_file_path argument in get_handler functions is deprecated. Use tool_config.get('config_file_path') instead.

The config_file_path argument is now deprecated and only passed to get_handler functions if they accept it. If you used it to compute a "base directory", you can now use the tool_config argument instead, which is the configuration of the SSG tool in use (here MkDocs):

base_dir = Path(tool_config.config_file_path or "./mkdocs.yml").parent

Most of these warnings will disappear with the next version of mkdocstrings-python.

Bug Fixes¤

Update handlers in JSON schema to be an object instead of an array (3cf7d51 by Matthew Messinger). Issue-733, PR-734
Fix broken table of contents when nesting autodoc instructions (12c8f82 by Timothée Mazzucotelli). Issue-348

Code Refactoring¤

Pass config_file_path to get_handler if it expects it (8c476ee by Timothée Mazzucotelli).
Give back inventory control to handlers (b84653f by Timothée Mazzucotelli). Related-to-issue-719
Give back control to handlers on how they want to handle global/local options (c00de7a by Timothée Mazzucotelli). Issue-719
Deprecate base handler's get_anchors method in favor of get_aliases method (7a668f0 by Timothée Mazzucotelli).
Register all identifiers of rendered objects into autorefs (434d8c7 by Timothée Mazzucotelli).
Use mkdocs-get-deps' download utility to remove duplicated code (bb87cd8 by Timothée Mazzucotelli).
Clean up data passed down from plugin to extension and handlers (b8e8703 by Timothée Mazzucotelli). PR-726

0.27.0 - 2024-11-08¤

Compare with 0.26.2

Features¤

Add support for authentication in inventory file URLs (1c23c1b by Stefan Mejlgaard). Issue-707, PR-710

Performance Improvements¤

Reduce footprint of template debug messages (5648e5a by Timothée Mazzucotelli).

Code Refactoring¤

Use %-formatting for logging messages (0bbb8ca by Timothée Mazzucotelli).

0.26.2 - 2024-10-12¤

Compare with 0.26.1

Build¤

Drop support for Python 3.8 (f26edeb by Timothée Mazzucotelli).

0.26.1 - 2024-09-06¤

Compare with 0.26.0

Bug Fixes¤

Instantiate config of the autorefs plugin when it is not enabled by the user (db2ab34 by Timothée Mazzucotelli). Issue-autorefs#57

0.26.0 - 2024-09-02¤

Compare with 0.25.2

Build¤

Upgrade Python-Markdown lower bound to 3.6 (28565f9 by Timothée Mazzucotelli).

Dependencies¤

Depend on mkdocs-autorefs v1 (33aa573 by Timothée Mazzucotelli).

Features¤

Allow hooking into autorefs when converting Markdown docstrings (b63e726 by Timothée Mazzucotelli). Based-on-PR-autorefs#46

0.25.2 - 2024-07-25¤

Compare with 0.25.1

Code Refactoring¤

Give precedence to Markdown heading level (##) (2e5f89e by Timothée Mazzucotelli).

0.25.1 - 2024-05-05¤

Compare with 0.25.0

Bug Fixes¤

Always descend into sub-headings when re-applying their label (cb86e08 by Timothée Mazzucotelli). Issue-mkdocstrings/python-158

0.25.0 - 2024-04-27¤

Compare with 0.24.3

Features¤

Support once parameter in logging methods, allowing to log a message only once with a given logger (1532b59 by Timothée Mazzucotelli).
Support blank line between ::: path and YAML options (d799d2f by Timothée Mazzucotelli). Issue-450

Code Refactoring¤

Allow specifying name of template loggers (c5b5f69 by Timothée Mazzucotelli).

0.24.3 - 2024-04-05¤

Compare with 0.24.2

Bug Fixes¤

Support HTML toc labels with Python-Markdown 3.6+ (uncomment code...) (7fe3e5f by Timothée Mazzucotelli).

0.24.2 - 2024-04-02¤

Compare with 0.24.1

Bug Fixes¤

Support HTML toc labels with Python-Markdown 3.6+ (c0d0090 by Timothée Mazzucotelli). Issue-mkdocstrings/python-143

0.24.1 - 2024-02-27¤

Compare with 0.24.0

Code Refactoring¤

Support new pymdownx-highlight options (a7a2907 by Timothée Mazzucotelli).
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

0.24.0 - 2023-11-14¤

Compare with 0.23.0

Features¤

Cache downloaded inventories as local file (ce84dd5 by Oleh Prypin). PR #632

Bug Fixes¤

Make custom_templates relative to the config file (370a61d by Waylan Limberg). Issue #477, PR #627
Remove duplicated headings for docstrings nested in tabs/admonitions (e2123a9 by Perceval Wajsburt, f4a94f7 by Oleh Prypin). Issue #609, PR #610, PR #613

Code Refactoring¤

Drop support for MkDocs < 1.4, modernize usages (b61d4d1 by Oleh Prypin). PR #629

0.23.0 - 2023-08-28¤

Compare with 0.22.0

Breaking Changes¤

Removed BaseCollector and BaseRenderer classes: they were merged into the BaseHandler class.
Removed the watch feature, as MkDocs now provides it natively.
Removed support for selection and rendering keys in YAML blocks: use options instead.
Removed support for loading handlers from the mkdocstrings.handler namespace. Handlers must now be packaged under the mkdocstrings_handlers namespace.

Features¤

Register all anchors for each object in the inventory (228fb73 by Timothée Mazzucotelli).

Bug Fixes¤

Don't add codehilite CSS class to inline code (7690d41 by Timothée Mazzucotelli).
Support cross-references for API docs rendered in top-level index page (b194452 by Timothée Mazzucotelli).

Code Refactoring¤

Sort inventories before writing them to disk (9371e9f by Timothée Mazzucotelli).
Stop accepting sets as return value of get_anchors (only tuples), to preserve order (2e10374 by Timothée Mazzucotelli).
Remove deprecated parts (0a90a47 by Timothée Mazzucotelli).
Use proper parameters in Inventory.register method (433c6e0 by Timothée Mazzucotelli).

0.22.0 - 2023-05-25¤

Compare with 0.21.2

Features¤

Allow extensions to add templates (cf0af05 by Timothée Mazzucotelli). PR #569

Code Refactoring¤

Report inventory loading errors (2c05d78 by Timothée Mazzucotelli). Co-authored-by: Oleh Prypin oleh@pryp.in

0.21.2 - 2023-04-06¤

Compare with 0.21.1

Bug Fixes¤

Fix regression with LRU cached method (85efbd2 by Timothée Mazzucotelli). Issue #549

0.21.1 - 2023-04-05¤

Compare with 0.21.0

Bug Fixes¤

Fix missing typing-extensions dependency on Python less than 3.10 (bff760b by Timothée Mazzucotelli). Issue #548

0.21.0 - 2023-04-05¤

Compare with 0.20.0

Features¤

Expose the full config to handlers (15dacf6 by David Patterson). Issue #501, PR #509

0.20.0 - 2023-01-19¤

Compare with 0.19.1

Features¤

Add enabled configuration option (8cf117d by StefanBRas). Issue #478, PR #504

Bug Fixes¤

Handle updating Jinja environment of multiple handlers (a6ea80c by David Patterson). Related PR #201, Issue #502, PR #507

Code Refactoring¤

Make _load_inventory accept lists as arguments (105ed82 by Sorin Sbarnea). Needed by PR mkdocstrings/python#49, PR #511
Remove support for MkDocs < 1.2 (we already depended on MkDocs >= 1.2) (ac963c8 by Timothée Mazzucotelli).

0.19.1 - 2022-12-13¤

Compare with 0.19.0

Bug Fixes¤

Fix regular expression for Sphinx inventory parsing (348bdd5 by Luis Michaelis). Issue #496, PR #497

Code Refactoring¤

Small fixes to type annotations (9214b74 by Oleh Prypin). PR #470
Report usage-based warnings as user-facing messages (03dd7a6 by Oleh Prypin). PR #464

0.19.0 - 2022-05-28¤

Compare with 0.18.1

Highlights¤

We decided to deprecate a few things to pave the way towards a more stable code base, bringing us closer to a v1.

Selection and rendering options are now combined into a single options key. Using the old keys will emit a deprecation warning.
The BaseCollector and BaseRenderer classes are deprecated in favor of BaseHandler, which merges their functionality. Using the old classes will emit a deprecation warning.

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 members and filters options that prevented many users to switch to it.

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.

Packaging / Dependencies¤

Stop depending directly on mkdocstrings-python-legacy (9055d58 by Timothée Mazzucotelli). Issue #376

Features¤

Pass config file path to handlers (cccebc4 by Timothée Mazzucotelli). Issue #311, PR #425

Code Refactoring¤

Support options / deprecated options mix-up (7c71f26 by Timothée Mazzucotelli).
Deprecate watch feature in favor of MkDocs' built-in one (c20022e by Timothée Mazzucotelli).
Log relative template paths if possible, instead of absolute (91f5f83 by Timothée Mazzucotelli).
Deprecate selection and rendering YAML keys (3335310 by Timothée Mazzucotelli). PR #420
Deprecate BaseCollector and BaseRenderer (eb822cb by Timothée Mazzucotelli). PR #413

0.18.1 - 2022-03-01¤

Compare with 0.18.0

Bug Fixes¤

Don't preemptively register identifiers as anchors (c7ac043 by Timothée Mazzucotelli).

0.18.0 - 2022-02-06¤

Compare with 0.17.0

Highlights¤

Python 3.6 support is dropped.
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 mkdocs.yml. See migration notes in the documentation.
The "legacy" Python handler now lives in its own repository at https://github.com/mkdocstrings/python-legacy.

Packaging / Dependencies¤

Add Crystal extra, update Python extras versions (b8222b0 by Timothée Mazzucotelli). PR #374
Update autorefs to actually required version (fc6c7f6 by Timothée Mazzucotelli).
Drop Python 3.6 support (7205ac6 by Timothée Mazzucotelli).

Features¤

Allow unwrapping the <p> tag in convert_markdown filter (5351fc8 by Oleh Prypin). PR #369
Support handlers spanning multiple locations (f42dfc6 by Timothée Mazzucotelli). PR #355

Code Refactoring¤

Prefix logs with the package name only (6c2b734 by Timothée Mazzucotelli). PR #375
Extract the Python handler into its own repository (74371e4 by Timothée Mazzucotelli). PR #356
Support Jinja2 3.1 (b377227 by Timothée Mazzucotelli). Issue #360, PR #361
Find templates in new and deprecated namespaces (d5d5f18 by Timothée Mazzucotelli). PR #367
Support loading handlers from the mkdocstrings_handlers namespace (5c22c6c by Timothée Mazzucotelli). PR #367

0.17.0 - 2021-12-27¤

Compare with 0.16.2

Features¤

Add show_signature rendering option (024ee82 by Will Da Silva). Issue #341, PR #342
Support Keyword Args and Yields sections (1286427 by Timothée Mazzucotelli). Issue #205 and #324, PR #331

Bug Fixes¤

Do minimum work when falling back to re-collecting an object to get its anchor (f6cf570 by Timothée Mazzucotelli). Issue #329, PR #330

Code Refactoring¤

Return multiple identifiers from fallback method (78c498c by Timothée Mazzucotelli). Issue mkdocstrings/autorefs#11, PR #350

0.16.2 - 2021-10-04¤

Compare with 0.16.1

Dependencies¤

Support pymdown-extensions v9.x (0831343 by Ofek Lev and 38b22ec by Timothée Mazzucotelli).

0.16.1 - 2021-09-23¤

Compare with 0.16.0

Bug Fixes¤

Fix ReadTheDocs "return" template (598621b by Timothée Mazzucotelli).

0.16.0 - 2021-09-20¤

Compare with 0.15.0

Features¤

Add a rendering option to change the sorting of members (b1fff8b by Joe Rickerby). Issue #114, PR #274
Add option to show Python base classes (436f550 by Brian Koropoff). Issue #269, PR #297
Support loading external Python inventories in Sphinx format (a8418cb by Oleh Prypin). PR #287
Support loading external inventories and linking to them (8b675f4 by Oleh Prypin). PR #277
Very basic support for MkDocs theme (974ca90 by Oleh Prypin). PR #272
Generate objects inventory (14ed959 and bbd85a9 by Timothée Mazzucotelli). Issue #251, PR #253

Bug Fixes¤

Don't render empty code blocks for missing type annotations (d2e9e1e by Oleh Prypin).
Fix custom handler not being used (6dcf342 by Timothée Mazzucotelli). Issue #259, PR #263
Don't hide setup_commands errors (92418c4 by Gabriel Vîjială). PR #258

Code Refactoring¤

Move writing extra files to an earlier stage in the build (3890ab5 by Oleh Prypin). PR #275

0.15.2 - 2021-06-09¤

Compare with 0.15.1

Packaging¤

MkDocs default schema needs to be obtained differently now (b3e122b by Oleh Prypin). PR #273
Compatibility with MkDocs 1.2: livereload isn't guaranteed now (36e8024 by Oleh Prypin). PR #294

0.15.1 - 2021-05-16¤

Compare with 0.15.0

Bug Fixes¤

Prevent error during parallel installations (fac2c71 by Timothée Mazzucotelli).

Packaging¤

Support the upcoming major Jinja and MarkupSafe releases (bb4f9de by Oleh Prypin). PR #283
Accept a higher version of mkdocs-autorefs (c8de08e by Oleh Prypin). PR #282

0.15.0 - 2021-02-28¤

Compare with 0.14.0

Breaking Changes¤

The following items are possible breaking changes:

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.
mkdocstrings now respects your configured code highlighting method, so if you are using the CodeHilite extension, the .highlight CSS class in the rendered HTML will become .codehilite. 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.
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 extra_css, similarly to this diff.

Features¤

Nicer-looking error outputs - no tracebacks from mkdocstrings (6baf720 by Oleh Prypin). PR #230
Let handlers add CSS to the pages, do so for Python handler (05c7a3f by Oleh Prypin). Issue #189, PR #218
Allow linking to an object heading not only by its canonical identifier, but also by its possible aliases (4789950 by Oleh Prypin). PR #217

Bug Fixes¤

Propagate the CSS class to inline highlighting as well (c7d80e6 by Oleh Prypin). PR #245
Don't double-escape characters in highlighted headings (6357144 by Oleh Prypin). Issue #228, PR #241

Code Refactoring¤

Use the autorefs plugin from its new external location (e2d74ef by Oleh Prypin). PR #235
Split out Markdown extensions from handlers to handlers.rendering (7533852 by Oleh Prypin). PR #233
Theme-agnostic code highlighting, respecting configs (f9ea009 by Oleh Prypin). PR #202
Split out autorefs plugin, make it optional (fc67656 by Oleh Prypin). PR #220
Remove the extra wrapper div from the final doc (7fe438c by Oleh Prypin). PR #209
Don't re-parse the whole subdoc, expose only headings (15f84f9 by Oleh Prypin). PR #209
Actually exclude hidden headings from the doc (0fdb082 by Oleh Prypin). PR #209

0.14.0 - 2021-01-06¤

Compare with 0.13.6

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!

Bug Fixes¤

Fix double code tags (e84d401 by Timothée Mazzucotelli).
Don't mutate the original Markdown config for permalinks (8f6b163 by Oleh Prypin).
Preserve text immediately before an autodoc (07466fa by Oleh Prypin). PR #207
Remove href attributes from headings in templates (d5602ff by Oleh Prypin). PR #204
Don't let toc extension append its permalink twice (a154f5c by Oleh Prypin). PR #203
Fix undefined entity for ¶ (2c29211 by Timothée Mazzucotelli).
Make ids of Markdown sub-documents prefixed with the parent item id (d493d33 by Oleh Prypin). Issue #186 and #193, PR #199
More lenient regex for data-mkdocstrings-identifier (dcfec8e by Oleh Prypin).
Shift Markdown headings according to the current heading_level (13f41ae by Oleh Prypin). Issue #192, PR #195
Fix footnotes appearing in all following objects (af24bc2 by Oleh Prypin). Issue #186, PR #195
Fix cross-references from the root index page (9c9f2a0 by Oleh Prypin). Issue #184, PR #185
Fix incorrect argument name passed to Markdown (10ce502 by Timothée Mazzucotelli).
Fix error when a digit immediately follows a code tag (9b92341 by Oleh Prypin). Issue #169, PR #175
Detecting paths relative to template directory in logging (a50046b by Oleh Prypin). Issue #166

Code Refactoring¤

BlockProcessor already receives strings, use them as such (bcf7da9 by Oleh Prypin).
Remove some unused code (8504084 by Oleh Prypin). PR #206
Improve XML parsing error handling (ad86410 by Timothée Mazzucotelli).
Explicitly use MarkupSafe (6b9ebe7 by Oleh Prypin).
Split out the handler cache, expose it through the plugin (6453026 by Oleh Prypin). Issue #179, PR #191
Use ChainMap instead of copying dicts (c634d2c by Oleh Prypin). PR #171
Rename logging to loggers to avoid confusion (7a119cc by Timothée Mazzucotelli).
Simplify logging (409f93e by Timothée Mazzucotelli).

Features¤

Allow specifying heading_level as a Markdown heading (10efc28 by Oleh Prypin). PR #170
Allow any characters in identifiers (7ede68a by Oleh Prypin). PR #174
Allow namespace packages for handlers (39b0465 by Timothée Mazzucotelli).
Add template debugging/logging (33b32c1 by Timothée Mazzucotelli).
Add initial support for the ReadTheDocs theme (1028115 by Timothée Mazzucotelli). Issue #107, PR #159
Add option to show type annotations in signatures (f94ce9b by Timothée Mazzucotelli). Issue #106

Packaging¤

Accept verions of pytkdocs up to 0.10.x (see changelog).

Performance Improvements¤

Call update_env only once per Markdown instance (b198c74 by Oleh Prypin). PR #201
Disable Jinja's auto_reload to reduce disk reads (3b28c58 by Oleh Prypin). PR #200
Rework autorefs replacement to not re-parse the final HTML (22a9e4b by Oleh Prypin). Issue #187, PR #188

0.13.6 - 2020-09-28¤

Compare with 0.13.5

Bug Fixes¤

Fix rendering when clicking on hidden toc entries (2af4d31 by Timothée Mazzucotelli). Issue #60.

0.13.5 - 2020-09-28¤

Compare with 0.13.4

Packaging¤

Accept pytkdocs version up to 0.9.x (changelog).

0.13.4 - 2020-09-25¤

Compare with 0.13.3

Bug Fixes¤

Bring back arbitrary **config to Python handler (fca7d4c by Florimond Manca). Issue #154, PR #155

0.13.3 - 2020-09-25¤

Compare with 0.13.2

Packaging¤

Accept pytkdocs version up to 0.8.x (changelog).

0.13.2 - 2020-09-08¤

Compare with 0.13.1

Bug Fixes¤

Fix relative URLs when use_directory_urls is false (421d189 by Timothée Mazzucotelli). References: #149

0.13.1 - 2020-09-03¤

Compare with 0.13.0

Bug Fixes¤

Use relative links for cross-references (9c77f1f by Timothée Mazzucotelli). References: #144, #147

0.13.0 - 2020-08-21¤

Compare with 0.12.2

Bug Fixes¤

Accept dashes in module names (fcf79d0 by Timothée Mazzucotelli). References: #140

Features¤

Add option to show full path of direct members only (d1b9401 by Aaron Dunmore). References: #134, #136

Packaging¤

Accept pymdown-extensions versions up to 0.8.x (see release notes) (178d48d by Hugo van Kemenade). PR #146

0.12.2 - 2020-07-24¤

Compare with 0.12.1

Packaging¤

Accept pytkdocs version up to 0.7.x (changelog).

0.12.1 - 2020-07-07¤

Compare with 0.12.0

Bug Fixes¤

Fix HTML-escaped sequence parsing as XML (db297f1 by Timothée Mazzucotelli).
Allow running mkdocs from non-default interpreter (283dd7b by Jared Khan).

0.12.0 - 2020-06-14¤

Compare with 0.11.4

Features¤

Support attributes section in Google-style docstrings (8300253 by Timothée Mazzucotelli). References: #88
Support examples section in Google-style docstrings (650c754 by Iago González). References: #112

Packaging¤

Accept pytkdocs version up to 0.6.x (changelog).

0.11.4 - 2020-06-08¤

Compare with 0.11.3

Packaging¤

Accept pytkdocs version up to 0.5.x (changelog). If it breaks your docs, please open issues on pytkdocs' bug-tracker, or pin pytkdocs version to while waiting for bug fixes <0.5.0 .

0.11.3 - 2020-06-07¤

Compare with 0.11.2

Bug Fixes¤

Support custom theme directory configuration (1243cf6 by Abhishek Thakur). References: #120, #121

0.11.2 - 2020-05-20¤

Compare with 0.11.1

Packaging¤

Increase pytkdocs version range to accept 0.4.0 (changelog).

0.11.1 - 2020-05-14¤

Compare with 0.11.0

Bug Fixes¤

Fix integration with mkdocs logging une bonne fois pour toute (3293cbf by Timothée Mazzucotelli).
Discard setup commands stdout (ea44cea by Timothée Mazzucotelli). References: #91
Use the proper python executable to start subprocesses (9fe3b39 by Reece Dunham). References: #91, #103

0.11.0 - 2020-04-23¤

Compare with 0.10.3

Bug Fixes¤

Properly raise on errors (respect strict mode) (2097208 by Timothée Mazzucotelli). Related issues/PRs: #86
Hook properly to MkDocs logging (b23daed by Timothée Mazzucotelli). Related issues/PRs: #86

Features¤

Add setup_commands option to python handler (599f8e5 by Ross Mechanic). Related issues/PRs: #89, #90
Add option to allow overriding templates (7360021 by Mikaël Capelle). Related issues/PRs: #59, #82

0.10.3 - 2020-04-10¤

Compare with 0.10.2

Bug Fixes¤

Handle site_url not being defined (9fb4a9b by Timothée Mazzucotelli). Related issues/PRs: #77

Packaging¤

This version increases the accepted range of versions for the pytkdocs dependency to >=0.2.0, <0.4.0. The pytkdocs project just released version 0.3.0 which:

adds support for complex markup in docstrings sections items descriptions
adds support for different indentations in docstrings sections (tabulations or less/more than 4 spaces)
fixes docstring parsing for arguments whose names start with *, like *args and **kwargs

0.10.2 - 2020-04-07¤

Compare with 0.10.1

Packaging¤

This version increases the accepted range of versions for the pymdown-extensions dependency, as well as for the mkdocs-material 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.

0.10.1 - 2020-04-03¤

Compare with 0.10.0

Bug Fixes¤

Fix jinja2 error for jinja2 < 2.11 (387f970 by Timothée Mazzucotelli). Related issues/PRs: #67, #72
Fix missing dependency pymdown-extensions (648b99d by Timothée Mazzucotelli). Related issues/PRs: #66
Fix heading level of hidden toc entries (475cc62 by Timothée Mazzucotelli). Related issues/PRs: #65
Fix rendering signatures containing keyword_only (c6c5add by Timothée Mazzucotelli). Related issues/PRs: #68

0.10.0 - 2020-03-27¤

Compare with 0.9.1

Features¤

Prepare for new pytkdocs version (336421a). Add options filters and members to the Python collector to reflect the new pytkdocs options. See the default configuration of the Python collector.

0.9.1 - 2020-03-21¤

Compare with 0.9.0

Bug fixes¤

Fix cross-references when deploying to GitHub pages (36f804b).

0.9.0 - 2020-03-21¤

Compare with 0.8.0

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.

Features¤

Language agnostic: we moved the code responsible for loading Python documentation into a new project, pytkdocs, and implemented a "handlers" logic, effectively allowing to support any given language. Waiting for your handlers contributions !
Multiple themes support: handlers can offer templates for multiple mkdocs themes.
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.
Configuration options: the rendering of Python documentation can now be configured, (globally and locally thanks to the handlers system), check the docs! Also see the recommended CSS.
Proper logging messages: mkdocstrings now logs debug, warning and error messages, useful when troubleshooting.

Bug fixes¤

Various fixes and better error handling.

0.8.0 - 2020-03-04¤

Compare with 0.7.2

Breaking Changes¤

Be compatible with Mkdocs >= 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.

0.7.2 - 2020-03-04¤

Compare with 0.7.1

Bug Fixes¤

Catch OSError when trying to get source lines (8e8d604).
Do not render signature empty sentinel (16dfd73).
Fix for nested classes and their attributes (7fef903).
Fix relative_file_path method (52715ad).
Wrap file path in backticks to escape it (2525f39).

0.7.1 - 2020-02-18¤

Compare with 0.7.0

Bug Fixes¤

Replace literal slash with os.sep for Windows compatibility (70f9af5).

0.7.0 - 2020-01-13¤

Compare with 0.6.1

Bug Fixes¤

Don't mark args or kwargs as required (4049d6f).
Filter submodules (7b11095).

Code Refactoring¤

Don't guess lang in generated docs (db4f60a).
Render at HTML step with custom markdown converter (9b5a3e1).

Features¤

Change forward ref to ref, fix optional unions (2f0bfaa).
Discover package submodules (231062a).
Implement watched source code (hacks) (4a67953).

0.6.1 - 2020-01-02¤

Compare with 0.6.0

Bug Fixes¤

Break docstring discarding loop if found (5a17fec).
Fix discarding docstring (143f7cb).
Fix getting annotation from nodes (ecde72b).
Fix various things (affbf06).

Code Refactoring¤

Break as soon as we find the same attr in a parent class while trying to discard the docstring (65d7908).
Split Docstring.parse method to improve readability (2226e2d).