This PR contains the following updates:
| Package | Type | Update | Change |
|---|---|---|---|
| [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings) ([changelog](https://mkdocstrings.github.io/changelog)) | dependency-groups | minor | `==0.27.0` -> `==0.29.0` |
---
### Release Notes
<details>
<summary>mkdocstrings/mkdocstrings (mkdocstrings)</summary>
### [`v0.29.0`](https://github.com/mkdocstrings/mkdocstrings/blob/HEAD/CHANGELOG.md#0290---2025-03-10)
[Compare Source](https://github.com/mkdocstrings/mkdocstrings/compare/0.28.3...0.29.0)
<small>[Compare with 0.28.3](https://github.com/mkdocstrings/mkdocstrings/compare/0.28.3...0.29.0)</small>
**This is the last version before v1!**
##### Build
- Depend on MkDocs 1.6 ([11bc400](11bc400ab7) by Timothée Mazzucotelli).
##### Features
- Support rendering backlinks through handlers ([d4c7b9c](d4c7b9c42f) by Timothée Mazzucotelli). [Issue-723](https://github.com/mkdocstrings/mkdocstrings/issues/723), [Issue-mkdocstrings-python-153](https://github.com/mkdocstrings/python/issues/153), [PR-739](https://github.com/mkdocstrings/mkdocstrings/pull/739)
##### Code Refactoring
- Save and forward titles to autorefs ([f49fb29](f49fb29582) by Timothée Mazzucotelli).
- Use a combined event (each split with a different priority) for `on_env` ([8d1dd75](8d1dd754b4) by Timothée Mazzucotelli).
### [`v0.28.3`](https://github.com/mkdocstrings/mkdocstrings/blob/HEAD/CHANGELOG.md#0283---2025-03-08)
[Compare Source](https://github.com/mkdocstrings/mkdocstrings/compare/0.28.2...0.28.3)
<small>[Compare with 0.28.2](https://github.com/mkdocstrings/mkdocstrings/compare/0.28.2...0.28.3)</small>
##### Deprecations
All public objects must now be imported from the top-level `mkdocstrings` module. Importing from submodules is deprecated, and will raise errors starting with v1. This should be the last deprecation before v1.
##### Build
- Make `python` extra depend on latest mkdocstrings-python (1.16.2) ([ba9003e](ba9003e96c) by Timothée Mazzucotelli).
##### Code Refactoring
- Finish exposing/hiding public/internal objects ([0723fc2](0723fc25fd) by Timothée Mazzucotelli).
- Re-expose public API in the top-level `mkdocstrings` module ([e66e080](e66e08096d) by Timothée Mazzucotelli).
- Move modules to internal folder ([23fe23f](23fe23f110) by Timothée Mazzucotelli).
### [`v0.28.2`](https://github.com/mkdocstrings/mkdocstrings/blob/HEAD/CHANGELOG.md#0282---2025-02-24)
[Compare Source](https://github.com/mkdocstrings/mkdocstrings/compare/0.28.1...0.28.2)
<small>[Compare with 0.28.1](https://github.com/mkdocstrings/mkdocstrings/compare/0.28.1...0.28.2)</small>
##### Build
- Depend on mkdocs-autorefs >= 1.4 ([2c22bdc](2c22bdc49f) by Timothée Mazzucotelli).
### [`v0.28.1`](https://github.com/mkdocstrings/mkdocstrings/blob/HEAD/CHANGELOG.md#0281---2025-02-14)
[Compare Source](https://github.com/mkdocstrings/mkdocstrings/compare/0.28.0...0.28.1)
<small>[Compare with 0.28.0](https://github.com/mkdocstrings/mkdocstrings/compare/0.28.0...0.28.1)</small>
##### Bug Fixes
- Renew MkDocs' `relpath` processor instead of using same instance ([4ab180d](4ab180d019) by Timothée Mazzucotelli). [Issue-mkdocs-3919](https://github.com/mkdocs/mkdocs/issues/3919)
### [`v0.28.0`](https://github.com/mkdocstrings/mkdocstrings/blob/HEAD/CHANGELOG.md#0280---2025-02-03)
[Compare Source](https://github.com/mkdocstrings/mkdocstrings/compare/0.27.0...0.28.0)
<small>[Compare with 0.27.0](https://github.com/mkdocstrings/mkdocstrings/compare/0.27.0...0.28.0)</small>
##### 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.
```python
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.
```python
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`:
\=== "Explicitly"
```python
def get_handler(..., mdx, ...):
return MyHandler(..., mdx=mdx, ...)
class MyHandler:
def __init__(self, ..., mdx, ...):
super().__init__(..., mdx=mdx, ...)
```
\=== "Through `**kwargs`"
```python
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.
```python
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.
```python
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.
```python
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.).
```python
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):
```python
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](3cf7d51704) by Matthew Messinger). [Issue-733](https://github.com/mkdocstrings/mkdocstrings/issues/733), [PR-734](https://github.com/mkdocstrings/mkdocstrings/pull/734)
- Fix broken table of contents when nesting autodoc instructions ([12c8f82](12c8f82e9a) by Timothée Mazzucotelli). [Issue-348](https://github.com/mkdocstrings/mkdocstrings/issues/348)
##### Code Refactoring
- Pass `config_file_path` to `get_handler` if it expects it ([8c476ee](8c476ee0b8) by Timothée Mazzucotelli).
- Give back inventory control to handlers ([b84653f](b84653f2b1) by Timothée Mazzucotelli). [Related-to-issue-719](https://github.com/mkdocstrings/mkdocstrings/issues/719)
- Give back control to handlers on how they want to handle global/local options ([c00de7a](c00de7a42b) by Timothée Mazzucotelli). [Issue-719](https://github.com/mkdocstrings/mkdocstrings/issues/719)
- Deprecate base handler's `get_anchors` method in favor of `get_aliases` method ([7a668f0](7a668f0f73) by Timothée Mazzucotelli).
- Register all identifiers of rendered objects into autorefs ([434d8c7](434d8c7cd1) by Timothée Mazzucotelli).
- Use mkdocs-get-deps' download utility to remove duplicated code ([bb87cd8](bb87cd833f) by Timothée Mazzucotelli).
- Clean up data passed down from plugin to extension and handlers ([b8e8703](b8e87036e0) by Timothée Mazzucotelli). [PR-726](https://github.com/mkdocstrings/mkdocstrings/pull/726)
</details>
---
### Configuration
📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.
♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 **Ignore**: Close this PR and you won't be reminded about this update again.
---
- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box
---
This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzOS4yMTEuMCIsInVwZGF0ZWRJblZlciI6IjM5LjIxMS4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->
Reviewed-on: #76
Co-authored-by: Renovate <renovate@csw.im>
Co-committed-by: Renovate <renovate@csw.im>
You'll need some prerequisites before you can start working on my cogs. git - uv
Additionally, I recommend a code editor of some variety. Visual Studio Code is a good, beginner-friendly option.
Installing Prerequisites
This section of the guide only applies to Windows systems.
If you're on Linux, refer to the documentation of the projects listed above. I also offer a Nix Flake that contains all of the required prerequisites, if you're a Nix user.
Renovate
e1b97974ae
