+
+
+
+
+
-
- - - - - If you sponsor publicly, you're automatically added here with a link to - your profile and avatar to show your support for *mkdocstrings*. - Alternatively, if you wish to keep your sponsorship private, you'll be a - silent +1. You can select visibility during checkout and change it - afterwards. - - -## Funding - -### Goals - -The following section lists all funding goals. Each goal contains a list of -features prefixed with a checkmark symbol, denoting whether a feature is -:octicons-check-circle-fill-24:{ style="color: #00e676" } already available or -:octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, -but not yet implemented. When the funding goal is hit, -the features are released for general availability. - -```python exec="1" session="insiders" idprefix="" -for goal in goals.values(): - if not goal.complete: - goal.render() -``` - -### Goals completed - -This section lists all funding goals that were previously completed, which means -that those features were part of Insiders, but are now generally available and -can be used by all users. - -```python exec="1" session="insiders" idprefix="" -for goal in goals.values(): - if goal.complete: - goal.render() -``` - -## Frequently asked questions - -### Compatibility - -> We're building an open source project and want to allow outside collaborators -to use *mkdocstrings* locally without having access to Insiders. -Is this still possible? - -Yes. Insiders is compatible with *mkdocstrings*. Almost all new features -and configuration options are either backward-compatible or implemented behind -feature flags. Most Insiders features enhance the overall experience, -though while these features add value for the users of your project, they -shouldn't be necessary for previewing when making changes to content. - -### Payment - -> We don't want to pay for sponsorship every month. Are there any other options? - -Yes. You can sponsor on a yearly basis by [switching your GitHub account to a -yearly billing cycle][billing cycle]. If for some reason you cannot do that, you -could also create a dedicated GitHub account with a yearly billing cycle, which -you only use for sponsoring (some sponsors already do that). - -If you have any problems or further questions, please reach out to insiders@pawamoy.fr. - -### Terms - -> Are we allowed to use Insiders under the same terms and conditions as -*mkdocstrings*? - -Yes. Whether you're an individual or a company, you may use *mkdocstrings -Insiders* precisely under the same terms as *mkdocstrings*, which are given -by the [ISC License][license]. However, we kindly ask you to respect our -**fair use policy**: - -- Please **don't distribute the source code** of Insiders. You may freely use - it for public, private or commercial projects, privately fork or mirror it, - but please don't make the source code public, as it would counteract the - sponsorware strategy. - -- If you cancel your subscription, you're automatically removed as a - collaborator and will miss out on all future updates of Insiders. However, you - may **use the latest version** that's available to you **as long as you like**. - Just remember that [GitHub deletes private forks][private forks]. - -[insiders]: #what-is-insiders -[sponsorship]: #what-sponsorships-achieve -[sponsors]: #how-to-become-a-sponsor -[features]: #whats-in-it-for-me -[funding]: #funding -[goals completed]: #goals-completed -[github sponsor profile]: https://github.com/sponsors/pawamoy -[billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle -[license]: ../license.md -[private forks]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository - - - diff --git a/docs/insiders/installation.md b/docs/insiders/installation.md deleted file mode 100644 index b7af7d2e..00000000 --- a/docs/insiders/installation.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Getting started with Insiders ---- - -# Getting started with Insiders - -*mkdocstrings Insiders* is a compatible drop-in replacement for *mkdocstrings*, -and can be installed similarly using `pip` or `git`. -Note that in order to access the Insiders repository, -you need to [become an eligible sponsor] of @pawamoy on GitHub. - - [become an eligible sponsor]: index.md#how-to-become-a-sponsor - -## Installation - -### with PyPI Insiders - -[PyPI Insiders](https://pawamoy.github.io/pypi-insiders/) -is a tool that helps you keep up-to-date versions -of Insiders projects in the PyPI index of your choice -(self-hosted, Google registry, Artifactory, etc.). - -See [how to install it](https://pawamoy.github.io/pypi-insiders/#installation) -and [how to use it](https://pawamoy.github.io/pypi-insiders/#usage). - -### with pip (ssh/https) - -*mkdocstrings Insiders* can be installed with `pip` [using SSH][using ssh]: - -```bash -pip install git+ssh://git@github.com/pawamoy-insiders/mkdocstrings.git -``` - - [using ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh - -Or using HTTPS: - -```bash -pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/mkdocstrings.git -``` - ->? NOTE: **How to get a GitHub personal access token** -> The `GH_TOKEN` environment variable is a GitHub token. -> It can be obtained by creating a [personal access token] for -> your GitHub account. It will give you access to the Insiders repository, -> programmatically, from the command line or GitHub Actions workflows: -> -> 1. Go to https://github.com/settings/tokens -> 2. Click on [Generate a new token] -> 3. Enter a name and select the [`repo`][scopes] scope -> 4. Generate the token and store it in a safe place -> -> [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token -> [Generate a new token]: https://github.com/settings/tokens/new -> [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes -> -> Note that the personal access -> token must be kept secret at all times, as it allows the owner to access your -> private repositories. - -### with pip (self-hosted) - -Self-hosting the Insiders package makes it possible to depend on *mkdocstrings* normally, -while transparently downloading and installing the Insiders version locally. -It means that you can specify your dependencies normally, and your contributors without access -to Insiders will get the public version, while you get the Insiders version on your machine. - -WARNING: **Limitation** -With this method, there is no way to force the installation of an Insiders version -rather than a public version. If there is a public version that is more recent -than your self-hosted Insiders version, the public version will take precedence. -Remember to regularly update your self-hosted versions by uploading latest distributions. - -You can build the distributions for Insiders yourself, by cloning the repository -and using [build] to build the distributions, -or you can download them from our [GitHub Releases]. -You can upload these distributions to a private PyPI-like registry -([Artifactory], [Google Cloud], [pypiserver], etc.) -with [Twine]: - - [build]: https://pypi.org/project/build/ - [Artifactory]: https://jfrog.com/help/r/jfrog-artifactory-documentation/pypi-repositories - [Google Cloud]: https://cloud.google.com/artifact-registry/docs/python - [pypiserver]: https://pypi.org/project/pypiserver/ - [Github Releases]: https://github.com/pawamoy-insiders/mkdocstrings/releases - [Twine]: https://pypi.org/project/twine/ - -```bash -# download distributions in ~/dists, then upload with: -twine upload --repository-url https://your-private-index.com ~/dists/* -``` - -You might also need to provide a username and password/token to authenticate against the registry. -Please check [Twine's documentation][twine docs]. - - [twine docs]: https://twine.readthedocs.io/en/stable/ - -You can then configure pip (or other tools) to look for packages into your package index. -For example, with pip: - -```bash -pip config set global.extra-index-url https://your-private-index.com/simple -``` - -Note that the URL might differ depending on whether your are uploading a package (with Twine) -or installing a package (with pip), and depending on the registry you are using (Artifactory, Google Cloud, etc.). -Please check the documentation of your registry to learn how to configure your environment. - -**We kindly ask that you do not upload the distributions to public registries, -as it is against our [Terms of use](index.md#terms).** - ->? TIP: **Full example with `pypiserver`** -> In this example we use [pypiserver] to serve a local PyPI index. -> -> ```bash -> pip install --user pypiserver -> # or pipx install pypiserver -> -> # create a packages directory -> mkdir -p ~/.local/pypiserver/packages -> -> # run the pypi server without authentication -> pypi-server run -p 8080 -a . -P . ~/.local/pypiserver/packages & -> ``` -> -> We can configure the credentials to access the server in [`~/.pypirc`][pypirc]: -> -> [pypirc]: https://packaging.python.org/en/latest/specifications/pypirc/ -> -> ```ini title=".pypirc" -> [distutils] -> index-servers = -> local -> -> [local] -> repository: http://localhost:8080 -> username: -> password: -> ``` -> -> We then clone the Insiders repository, build distributions and upload them to our local server: -> -> ```bash -> # clone the repository -> git clone git@github.com:pawamoy-insiders/mkdocstrings -> cd mkdocstrings -> -> # install build -> pip install --user build -> # or pipx install build -> -> # checkout latest tag -> git checkout $(git describe --tags --abbrev=0) -> -> # build the distributions -> pyproject-build -> -> # upload them to our local server -> twine upload -r local dist/* --skip-existing -> ``` -> -> Finally, we configure pip, and for example [PDM][pdm], to use our local index to find packages: -> -> ```bash -> pip config set global.extra-index-url http://localhost:8080/simple -> pdm config pypi.extra.url http://localhost:8080/simple -> ``` -> -> [pdm]: https://pdm.fming.dev/latest/ -> -> Now when running `pip install mkdocstrings`, -> or resolving dependencies with PDM, -> both tools will look into our local index and find the Insiders version. -> **Remember to update your local index regularly!** - -### with git - -Of course, you can use *mkdocstrings Insiders* directly from `git`: - -``` -git clone git@github.com:pawamoy-insiders/mkdocstrings -``` - -When cloning from `git`, the package must be installed: - -``` -pip install -e mkdocstrings -``` - -## Upgrading - -When upgrading Insiders, you should always check the version of *mkdocstrings* -which makes up the first part of the version qualifier. For example, a version like -`8.x.x.4.x.x` means that Insiders `4.x.x` is currently based on `8.x.x`. - -If the major version increased, it's a good idea to consult the [changelog] -and go through the steps to ensure your configuration is up to date and -all necessary changes have been made. - - [changelog]: ./changelog.md diff --git a/docs/js/feedback.js b/docs/js/feedback.js new file mode 100644 index 00000000..f97321a5 --- /dev/null +++ b/docs/js/feedback.js @@ -0,0 +1,14 @@ +const feedback = document.forms.feedback; +feedback.hidden = false; + +feedback.addEventListener("submit", function(ev) { + ev.preventDefault(); + const commentElement = document.getElementById("feedback"); + commentElement.style.display = "block"; + feedback.firstElementChild.disabled = true; + const data = ev.submitter.getAttribute("data-md-value"); + const note = feedback.querySelector(".md-feedback__note [data-md-value='" + data + "']"); + if (note) { + note.hidden = false; + } +}) diff --git a/docs/js/insiders.js b/docs/js/insiders.js deleted file mode 100644 index 8bb68485..00000000 --- a/docs/js/insiders.js +++ /dev/null @@ -1,74 +0,0 @@ -function humanReadableAmount(amount) { - const strAmount = String(amount); - if (strAmount.length >= 4) { - return `${strAmount.slice(0, strAmount.length - 3)},${strAmount.slice(-3)}`; - } - return strAmount; -} - -function getJSON(url, callback) { - var xhr = new XMLHttpRequest(); - xhr.open('GET', url, true); - xhr.responseType = 'json'; - xhr.onload = function () { - var status = xhr.status; - if (status === 200) { - callback(null, xhr.response); - } else { - callback(status, xhr.response); - } - }; - xhr.send(); -} - -function updatePremiumSponsors(dataURL, rank) { - let capRank = rank.charAt(0).toUpperCase() + rank.slice(1); - getJSON(dataURL + `/sponsors${capRank}.json`, function (err, sponsors) { - const sponsorsDiv = document.getElementById(`${rank}-sponsors`); - if (sponsors.length > 0) { - let html = ''; - html += `${capRank} sponsors
`
- sponsors.forEach(function (sponsor) {
- html += `
-
-
-
- `
- });
- html += '
` element directly, but rather the level gets shifted to fit the encompassing document structure. If you're curious about the implementation, check out [mkdocstrings.handlers.rendering.HeadingShiftingTreeprocessor][] and others.
+You may also notice that such a heading does not get rendered as a `` 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.
### Cross-references to other projects / inventories
@@ -271,7 +283,7 @@ plugins:
- mkdocstrings:
handlers:
python:
- import:
+ inventories:
- https://installer.readthedocs.io/en/stable/objects.inv
```
@@ -298,7 +310,7 @@ plugins:
- mkdocstrings:
handlers:
python:
- import:
+ inventories:
# latest instead of stable
- https://installer.readthedocs.io/en/latest/objects.inv
```
@@ -311,7 +323,7 @@ plugins:
- mkdocstrings:
handlers:
python:
- import:
+ inventories:
- url: https://cdn.example.com/version/objects.inv
base_url: https://docs.example.com/version
```
@@ -319,6 +331,24 @@ plugins:
Absolute URLs to cross-referenced items will then be based
on `https://docs.example.com/version/` instead of `https://cdn.example.com/version/`.
+If you need authentication to access the inventory file, you can provide the credentials in the URL, either as `username:password`:
+
+```yaml
+- url: https://username:password@private.example.com/version/objects.inv
+```
+
+...or with token authentication:
+
+```yaml
+- url: https://token123@private.example.com/version/objects.inv
+```
+
+The credentials can also be specified using environment variables in the form `${ENV_VAR}`:
+
+```yaml
+- url: https://${USERNAME}:${PASSWORD}@private.example.com/version/objects.inv
+```
+
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 `objects.inv` in the final site directory.
Other projects will be able to cross-reference items from your project.
diff --git a/docs/usage/theming.md b/docs/usage/theming.md
index b5d6f7b3..04d053f6 100644
--- a/docs/usage/theming.md
+++ b/docs/usage/theming.md
@@ -62,7 +62,7 @@ to modify small part of the templates without copy-pasting the whole files.
See the documentation about templates for:
- the Crystal handler: https://mkdocstrings.github.io/crystal/styling.html
-- the Python handler: https://mkdocstrings.github.io/python/customization/#templates
+- the Python handler: https://mkdocstrings.github.io/python/usage/customization/#templates
#### Debugging
@@ -86,11 +86,11 @@ we cannot list them all here. See the documentation about CSS classes for:
### Syntax highlighting
-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.handlers.rendering.Highlighter][].
+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][].
As for the CSS class used for code blocks -- it will also match the "normal" config, so the default (`.codehilite` or `.highlight`) will match your chosen Markdown extension for highlighting.
-IMPORTANT: **Changed in version 0.15.**
+IMPORTANT: **Changed in version 0.15.**
The CSS class used to always be `.highlight`, but now it depends on the configuration.
Long story short, you probably should add `pymdownx.highlight` to your `markdown_extensions`, and then use `.doc-contents .highlight` as the CSS selector in case you want to change something about *mkdocstrings'* code blocks specifically.
diff --git a/duties.py b/duties.py
index 30bf7c63..dfc81027 100644
--- a/duties.py
+++ b/duties.py
@@ -3,14 +3,12 @@
from __future__ import annotations
import os
+import re
import sys
-from contextlib import contextmanager
-from importlib.metadata import version as pkgversion
from pathlib import Path
-from typing import TYPE_CHECKING, Iterator
+from typing import TYPE_CHECKING
-from duty import duty
-from duty.callables import coverage, lazy, mkdocs, mypy, pytest, ruff, safety
+from duty import duty, tools
if TYPE_CHECKING:
from duty.context import Context
@@ -23,286 +21,186 @@
WINDOWS = os.name == "nt"
PTY = not WINDOWS and not CI
MULTIRUN = os.environ.get("MULTIRUN", "0") == "1"
+PY_VERSION = f"{sys.version_info.major}{sys.version_info.minor}"
+PY_DEV = "315"
-def pyprefix(title: str) -> str: # noqa: D103
+def pyprefix(title: str) -> str:
if MULTIRUN:
prefix = f"(python{sys.version_info.major}.{sys.version_info.minor})"
return f"{prefix:14}{title}"
return title
-@contextmanager
-def material_insiders() -> Iterator[bool]: # noqa: D103
- if "+insiders" in pkgversion("mkdocs-material"):
- os.environ["MATERIAL_INSIDERS"] = "true"
- try:
- yield True
- finally:
- os.environ.pop("MATERIAL_INSIDERS")
- else:
- yield False
+def _get_changelog_version() -> str:
+ changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$")
+ with Path(__file__).parent.joinpath("CHANGELOG.md").open("r", encoding="utf8") as file:
+ return next(filter(bool, map(changelog_version_re.match, file))).group(1) # ty: ignore[invalid-argument-type,unresolved-attribute]
@duty
-def changelog(ctx: Context) -> None:
+def changelog(ctx: Context, bump: str = "") -> None:
"""Update the changelog in-place with latest commits.
Parameters:
- ctx: The context instance (passed automatically).
+ bump: Bump option passed to git-changelog.
"""
- from git_changelog.cli import main as git_changelog
+ ctx.run(tools.git_changelog(bump=bump or None), title="Updating changelog")
+ ctx.run(tools.yore.check(bump=bump or _get_changelog_version()), title="Checking legacy code")
- ctx.run(git_changelog, args=[[]], title="Updating changelog")
+@duty(pre=["check-quality", "check-types", "check-docs", "check-api"])
+def check(ctx: Context) -> None:
+ """Check it all!"""
-@duty(pre=["check_quality", "check_types", "check_docs", "check_dependencies", "check-api"])
-def check(ctx: Context) -> None: # noqa: ARG001
- """Check it all!
- Parameters:
- ctx: The context instance (passed automatically).
- """
-
-
-@duty
+@duty(nofail=PY_VERSION == PY_DEV)
def check_quality(ctx: Context) -> None:
- """Check the code quality.
-
- Parameters:
- ctx: The context instance (passed automatically).
- """
+ """Check the code quality."""
ctx.run(
- ruff.check(*PY_SRC_LIST, config="config/ruff.toml"),
+ tools.ruff.check(*PY_SRC_LIST, config="config/ruff.toml", color=True),
title=pyprefix("Checking code quality"),
- command=f"ruff check --config config/ruff.toml {PY_SRC}",
)
-@duty
-def check_dependencies(ctx: Context) -> None:
- """Check for vulnerabilities in dependencies.
-
- Parameters:
- ctx: The context instance (passed automatically).
- """
- # retrieve the list of dependencies
- requirements = ctx.run(
- ["uv", "pip", "freeze"],
- silent=True,
- allow_overrides=False,
- )
-
+@duty(nofail=PY_VERSION == PY_DEV)
+def check_docs(ctx: Context) -> None:
+ """Check if the documentation builds correctly."""
ctx.run(
- safety.check(requirements),
- title="Checking dependencies",
- command="uv pip freeze | safety check --stdin",
+ tools.zensical.build(strict=True),
+ title=pyprefix("Building documentation"),
)
-@duty
-def check_docs(ctx: Context) -> None:
- """Check if the documentation builds correctly.
-
- Parameters:
- ctx: The context instance (passed automatically).
- """
- Path("htmlcov").mkdir(parents=True, exist_ok=True)
- Path("htmlcov/index.html").touch(exist_ok=True)
- with material_insiders():
- ctx.run(
- mkdocs.build(strict=True, verbose=True),
- title=pyprefix("Building documentation"),
- command="mkdocs build -vs",
- )
-
-
-@duty
+@duty(nofail=PY_VERSION == PY_DEV)
def check_types(ctx: Context) -> None:
- """Check that the code is correctly typed.
-
- Parameters:
- ctx: The context instance (passed automatically).
- """
- os.environ["MYPYPATH"] = "src"
+ """Check that the code is correctly typed."""
+ py = f"{sys.version_info.major}.{sys.version_info.minor}"
ctx.run(
- mypy.run(*PY_SRC_LIST, config_file="config/mypy.ini"),
+ tools.ty.check(
+ *PY_SRC_LIST,
+ config_file="config/ty.toml",
+ color=True,
+ error_on_warning=True,
+ python_version=py,
+ ),
title=pyprefix("Type-checking"),
- command=f"mypy --config-file config/mypy.ini {PY_SRC}",
)
-@duty
-def check_api(ctx: Context) -> None:
- """Check for API breaking changes.
-
- Parameters:
- ctx: The context instance (passed automatically).
- """
- from griffe.cli import check as g_check
-
- griffe_check = lazy(g_check, name="griffe.check")
+@duty(nofail=PY_VERSION == PY_DEV)
+def check_api(ctx: Context, *cli_args: str) -> None:
+ """Check for API breaking changes."""
ctx.run(
- griffe_check("mkdocstrings", search_paths=["src"], color=True),
+ tools.griffe.check("mkdocstrings", search=["src"], color=True).add_args(*cli_args),
title="Checking for API breaking changes",
- command="griffe check -ssrc mkdocstrings",
nofail=True,
)
-@duty(silent=True)
-def clean(ctx: Context) -> None:
- """Delete temporary files.
-
- Parameters:
- ctx: The context instance (passed automatically).
- """
-
- def _rm(*targets: str) -> None:
- for target in targets:
- ctx.run(f"rm -rf {target}")
-
- def _find_rm(*targets: str) -> None:
- for target in targets:
- ctx.run(f"find . -type d -name '{target}' | xargs rm -rf")
-
- _rm("build", "dist", ".coverage*", "htmlcov", "site", ".pdm-build")
- _find_rm(".cache", ".pytest_cache", ".mypy_cache", ".ruff_cache", "__pycache__")
-
-
@duty
-def docs(ctx: Context, host: str = "127.0.0.1", port: int = 8000) -> None:
+def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000) -> None:
"""Serve the documentation (localhost:8000).
Parameters:
- ctx: The context instance (passed automatically).
host: The host to serve the docs from.
port: The port to serve the docs on.
"""
- with material_insiders():
- ctx.run(
- mkdocs.serve(dev_addr=f"{host}:{port}"),
- title="Serving documentation",
- capture=False,
- )
+ ctx.run(
+ tools.zensical.serve(dev_addr=f"{host}:{port}").add_args(*cli_args),
+ title="Serving documentation",
+ capture=False,
+ )
@duty
def docs_deploy(ctx: Context) -> None:
- """Deploy the documentation on GitHub pages.
+ """Deploy the documentation to GitHub pages."""
+ from ghp_import import ghp_import # noqa: PLC0415
- Parameters:
- ctx: The context instance (passed automatically).
- """
- os.environ["DEPLOY"] = "true"
- with material_insiders() as insiders:
- if not insiders:
- ctx.run(lambda: False, title="Not deploying docs without Material for MkDocs Insiders!")
- origin = ctx.run("git config --get remote.origin.url", silent=True)
- if "pawamoy-insiders/mkdocstrings" in origin:
- ctx.run(
- "git remote add org-pages git@github.com:mkdocstrings/mkdocstrings.github.io",
- silent=True,
- nofail=True,
- )
- ctx.run(
- mkdocs.gh_deploy(remote_name="upstream", force=True),
- title="Deploying documentation",
- )
- else:
- ctx.run(
- lambda: False,
- title="Not deploying docs from public repository (do that from insiders instead!)",
- nofail=True,
- )
+ ctx.run(tools.zensical.build(), title="Building documentation site")
+ ctx.run(
+ ghp_import,
+ kwargs={
+ "srcdir": "site",
+ "mesg": "chore: Update documentation",
+ "push": True,
+ "force": True,
+ "remote": "org-pages",
+ },
+ title="Deploying site to GitHub Pages",
+ command="ghp-import site -r org-pages -fpm 'chore: Update documentation'",
+ pty=PTY,
+ )
@duty
def format(ctx: Context) -> None:
- """Run formatting tools on the code.
-
- Parameters:
- ctx: The context instance (passed automatically).
- """
+ """Run formatting tools on the code."""
ctx.run(
- ruff.check(*PY_SRC_LIST, config="config/ruff.toml", fix_only=True, exit_zero=True),
+ tools.ruff.check(*PY_SRC_LIST, config="config/ruff.toml", fix_only=True, exit_zero=True),
title="Auto-fixing code",
)
- ctx.run(ruff.format(*PY_SRC_LIST, config="config/ruff.toml"), title="Formatting code")
+ ctx.run(tools.ruff.format(*PY_SRC_LIST, config="config/ruff.toml"), title="Formatting code")
-@duty(post=["docs-deploy"])
-def release(ctx: Context, version: str) -> None:
+@duty
+def build(ctx: Context) -> None:
+ """Build source and wheel distributions."""
+ ctx.run(
+ ["uv", "build"],
+ title="Building distributions",
+ pty=PTY,
+ )
+
+
+@duty
+def publish(ctx: Context) -> None:
+ """Publish source and wheel distributions to PyPI."""
+ if not Path("dist").exists():
+ ctx.run("false", title="No distribution files found")
+ dists = [str(dist) for dist in Path("dist").iterdir() if dist.suffix in (".gz", ".whl")]
+ ctx.run(
+ tools.twine.upload(*dists, skip_existing=True),
+ title="Publishing distributions to PyPI",
+ pty=PTY,
+ )
+
+
+@duty(post=["build", "publish", "docs-deploy"])
+def release(ctx: Context, version: str = "") -> None:
"""Release a new Python package.
Parameters:
- ctx: The context instance (passed automatically).
version: The new version number to use.
"""
- origin = ctx.run("git config --get remote.origin.url", silent=True)
- if "pawamoy-insiders/mkdocstrings" in origin:
- ctx.run(
- lambda: False,
- title="Not releasing from insiders repository (do that from public repo instead!)",
- )
+ if not (version := (version or input("> Version to release: ")).strip()):
+ ctx.run("false", title="A version must be provided")
ctx.run("git add pyproject.toml CHANGELOG.md", title="Staging files", pty=PTY)
ctx.run(["git", "commit", "-m", f"chore: Prepare release {version}"], title="Committing changes", pty=PTY)
- ctx.run(f"git tag {version}", title="Tagging commit", pty=PTY)
+ ctx.run(f"git tag -m '' -a {version}", title="Tagging commit", pty=PTY)
ctx.run("git push", title="Pushing commits", pty=False)
ctx.run("git push --tags", title="Pushing tags", pty=False)
- ctx.run("pyproject-build", title="Building dist/wheel", pty=PTY)
- ctx.run("twine upload --skip-existing dist/*", title="Publishing version", pty=PTY)
-@duty(silent=True, aliases=["coverage"])
-def cov(ctx: Context) -> None:
- """Report coverage as text and HTML.
+@duty(silent=True, aliases=["cov"])
+def coverage(ctx: Context) -> None:
+ """Report coverage as text and HTML."""
+ ctx.run(tools.coverage.combine(), nofail=True)
+ ctx.run(tools.coverage.report(rcfile="config/coverage.ini"), capture=False)
+ ctx.run(tools.coverage.html(rcfile="config/coverage.ini"))
- Parameters:
- ctx: The context instance (passed automatically).
- """
- ctx.run(coverage.combine, nofail=True)
- ctx.run(coverage.report(rcfile="config/coverage.ini"), capture=False)
- ctx.run(coverage.html(rcfile="config/coverage.ini"))
-
-@duty
-def test(ctx: Context, match: str = "") -> None:
- """Run the test suite.
-
- Parameters:
- ctx: The context instance (passed automatically).
- match: A pytest expression to filter selected tests.
- """
- py_version = f"{sys.version_info.major}{sys.version_info.minor}"
- os.environ["COVERAGE_FILE"] = f".coverage.{py_version}"
+@duty(nofail=PY_VERSION == PY_DEV)
+def test(ctx: Context, *cli_args: str) -> None:
+ """Run the test suite."""
+ os.environ["COVERAGE_FILE"] = f".coverage.{PY_VERSION}"
+ os.environ["PYTHONWARNDEFAULTENCODING"] = "1"
ctx.run(
- pytest.run("-n", "auto", "tests", config_file="config/pytest.ini", select=match, color="yes"),
+ tools.pytest(
+ "tests",
+ config_file="config/pytest.ini",
+ color="yes",
+ ).add_args("-n", "auto", *cli_args),
title=pyprefix("Running tests"),
- command=f"pytest -c config/pytest.ini -n auto -k{match!r} --color=yes tests",
)
-
-
-@duty
-def vscode(ctx: Context) -> None:
- """Configure VSCode.
-
- This task will overwrite the following files,
- so make sure to back them up:
-
- - `.vscode/launch.json`
- - `.vscode/settings.json`
- - `.vscode/tasks.json`
-
- Parameters:
- ctx: The context instance (passed automatically).
- """
-
- def update_config(filename: str) -> None:
- source_file = Path("config", "vscode", filename)
- target_file = Path(".vscode", filename)
- target_file.parent.mkdir(exist_ok=True)
- target_file.write_text(source_file.read_text())
-
- for filename in ("launch.json", "settings.json", "tasks.json"):
- ctx.run(update_config, args=[filename], title=f"Update .vscode/{filename}")
diff --git a/mkdocs.yml b/mkdocs.yml
deleted file mode 100644
index 860ce66e..00000000
--- a/mkdocs.yml
+++ /dev/null
@@ -1,182 +0,0 @@
-site_name: "mkdocstrings"
-site_description: "Automatic documentation from sources, for MkDocs."
-site_url: "https://mkdocstrings.github.io/"
-repo_url: "https://github.com/mkdocstrings/mkdocstrings"
-repo_name: "mkdocstrings/mkdocstrings"
-site_dir: "site"
-watch: [mkdocs.yml, README.md, CONTRIBUTING.md, CHANGELOG.md, src/mkdocstrings]
-copyright: Copyright © 2019 Timothée Mazzucotelli
-edit_uri: edit/main/docs/
-
-validation:
- omitted_files: warn
- absolute_links: warn
- unrecognized_links: warn
-
-nav:
-- Home:
- - Overview: index.md
- - Changelog: changelog.md
- - Credits: credits.md
- - License: license.md
-- Usage:
- - usage/index.md
- - Theming: usage/theming.md
- - Handlers: usage/handlers.md
- - All handlers:
- - Crystal: https://mkdocstrings.github.io/crystal/
- - Python: https://mkdocstrings.github.io/python/
- - Python (Legacy): https://mkdocstrings.github.io/python-legacy/
- - Shell: https://mkdocstrings.github.io/shell/
- - VBA: https://pypi.org/project/mkdocstrings-vba
- - Guides:
- - Recipes: recipes.md
- - Troubleshooting: troubleshooting.md
-# defer to gen-files + literate-nav
-- API reference:
- - mkdocstrings: reference/
-- Development:
- - Contributing: contributing.md
- - Code of Conduct: code_of_conduct.md
- - Coverage report: coverage.md
-- Insiders:
- - insiders/index.md
- - Getting started:
- - Installation: insiders/installation.md
- - Changelog: insiders/changelog.md
-- Author's website: https://pawamoy.github.io/
-
-theme:
- name: material
- logo: logo.svg
- custom_dir: docs/.overrides
- features:
- - announce.dismiss
- - content.action.edit
- - content.action.view
- - content.code.annotate
- - content.code.copy
- - content.tooltips
- - navigation.footer
- - navigation.indexes
- - navigation.sections
- - navigation.tabs
- - navigation.tabs.sticky
- - navigation.top
- - search.highlight
- - search.suggest
- - toc.follow
- palette:
- - media: "(prefers-color-scheme)"
- toggle:
- icon: material/brightness-auto
- name: Switch to light mode
- - media: "(prefers-color-scheme: light)"
- scheme: default
- primary: teal
- accent: purple
- toggle:
- icon: material/weather-sunny
- name: Switch to dark mode
- - media: "(prefers-color-scheme: dark)"
- scheme: slate
- primary: black
- accent: lime
- toggle:
- icon: material/weather-night
- name: Switch to system preference
-
-extra_css:
-- css/style.css
-- css/material.css
-- css/mkdocstrings.css
-- css/insiders.css
-
-markdown_extensions:
-- attr_list
-- admonition
-- callouts
-- footnotes
-- pymdownx.details
-- pymdownx.emoji:
- emoji_index: !!python/name:material.extensions.emoji.twemoji
- emoji_generator: !!python/name:material.extensions.emoji.to_svg
-- pymdownx.highlight:
- pygments_lang_class: true
-- pymdownx.inlinehilite:
- style_plain_text: python
-- pymdownx.magiclink
-- pymdownx.snippets:
- base_path: [!relative $config_dir]
- check_paths: true
-- pymdownx.superfences
-- pymdownx.tabbed:
- alternate_style: true
- slugify: !!python/object/apply:pymdownx.slugs.slugify
- kwds:
- case: lower
-- pymdownx.tasklist:
- custom_checkbox: true
-- pymdownx.tilde
-- toc:
- permalink: "¤"
-
-plugins:
-- search
-- markdown-exec
-- gen-files:
- scripts:
- - scripts/gen_ref_nav.py
-- literate-nav:
- nav_file: SUMMARY.md
-- coverage
-- mkdocstrings:
- handlers:
- python:
- import:
- - https://docs.python.org/3/objects.inv
- - https://installer.readthedocs.io/en/stable/objects.inv # demonstration purpose in the docs
- - https://mkdocstrings.github.io/autorefs/objects.inv
- paths: [src]
- options:
- docstring_options:
- ignore_init_summary: true
- docstring_section_style: list
- filters: ["!^_"]
- heading_level: 1
- inherited_members: true
- merge_init_into_class: true
- separate_signature: true
- show_root_heading: true
- show_root_full_path: false
- show_signature_annotations: true
- show_symbol_type_heading: true
- show_symbol_type_toc: true
- signature_crossrefs: true
- summary: true
-- git-committers:
- enabled: !ENV [DEPLOY, false]
- repository: mkdocstrings/mkdocstrings
-- redirects:
- redirect_maps:
- theming.md: usage/theming.md
- handlers/overview.md: usage/handlers.md
-- minify:
- minify_html: !ENV [DEPLOY, false]
-- group:
- enabled: !ENV [MATERIAL_INSIDERS, false]
- plugins:
- - typeset
-
-extra:
- social:
- - icon: fontawesome/brands/github
- link: https://github.com/pawamoy
- - icon: fontawesome/brands/mastodon
- link: https://fosstodon.org/@pawamoy
- - icon: fontawesome/brands/twitter
- link: https://twitter.com/pawamoy
- - icon: fontawesome/brands/gitter
- link: https://gitter.im/mkdocstrings/community
- - icon: fontawesome/brands/python
- link: https://pypi.org/project/mkdocstrings/
diff --git a/pyproject.toml b/pyproject.toml
index b35e8dc7..9c722187 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,9 +6,10 @@ build-backend = "pdm.backend"
name = "mkdocstrings"
description = "Automatic documentation from sources, for MkDocs."
authors = [{name = "Timothée Mazzucotelli", email = "dev@pawamoy.fr"}]
-license = {text = "ISC"}
+license = "ISC"
+license-files = ["LICENSE"]
readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
keywords = ["mkdocs", "mkdocs-plugin", "docstrings", "autodoc", "documentation"]
dynamic = ["version"]
classifiers = [
@@ -17,11 +18,11 @@ classifiers = [
"Programming Language :: Python",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3 :: Only",
- "Programming Language :: Python :: 3.8",
- "Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
+ "Programming Language :: Python :: 3.13",
+ "Programming Language :: Python :: 3.14",
"Topic :: Documentation",
"Topic :: Software Development",
"Topic :: Software Development :: Documentation",
@@ -29,22 +30,18 @@ classifiers = [
"Typing :: Typed",
]
dependencies = [
- "click>=7.0",
- "Jinja2>=2.11.1",
- "Markdown>=3.3",
+ "Jinja2>=3.1",
+ "Markdown>=3.6",
"MarkupSafe>=1.1",
- "mkdocs>=1.4",
- "mkdocs-autorefs>=0.3.1",
- "platformdirs>=2.2.0",
+ "mkdocs>=1.6",
+ "mkdocs-autorefs>=1.4",
"pymdown-extensions>=6.3",
- "importlib-metadata>=4.6; python_version < '3.10'",
- "typing-extensions>=4.1; python_version < '3.10'",
]
[project.optional-dependencies]
crystal = ["mkdocstrings-crystal>=0.3.4"]
python-legacy = ["mkdocstrings-python-legacy>=0.2.1"]
-python = ["mkdocstrings-python>=0.5.2"]
+python = ["mkdocstrings-python>=1.16.2"]
[project.urls]
Homepage = "https://mkdocstrings.github.io"
@@ -57,11 +54,63 @@ Gitter = "https://gitter.im/mkdocstrings/community"
Funding = "https://github.com/sponsors/pawamoy"
[project.entry-points."mkdocs.plugins"]
-mkdocstrings = "mkdocstrings.plugin:MkdocstringsPlugin"
+mkdocstrings = "mkdocstrings:MkdocstringsPlugin"
-[tool.pdm]
-version = {source = "scm"}
+[tool.pdm.version]
+source = "call"
+getter = "scripts.get_version:get_version"
[tool.pdm.build]
-package-dir = "src"
-editable-backend = "editables"
+# Include as much as possible in the source distribution, to help redistributors.
+excludes = ["**/.pytest_cache"]
+source-includes = [
+ "config",
+ "docs",
+ "scripts",
+ "share",
+ "tests",
+ "duties.py",
+ "zensical.toml",
+ "*.md",
+ "LICENSE",
+]
+
+[tool.pdm.build.wheel-data]
+# Manual pages can be included in the wheel.
+# Depending on the installation tool, they will be accessible to users.
+# pipx supports it, uv does not yet, see https://github.com/astral-sh/uv/issues/4731.
+data = [
+ {path = "share/**/*", relative-to = "."},
+]
+
+[dependency-groups]
+maintain = [
+ "git-changelog>=2.5",
+ "twine>=5.1",
+ "yore>=0.3.3",
+]
+ci = [
+ "dirty-equals>=0.9",
+ "duty>=1.6",
+ "griffe>=2.0",
+ "pytest>=8.2",
+ "pytest-cov>=5.0",
+ "pytest-randomly>=3.15",
+ "pytest-xdist>=3.6",
+ "ruff>=0.4",
+ "ty>=0.0.14",
+ "types-markdown>=3.6",
+ "types-pyyaml>=6.0",
+]
+ docs = [
+ "ghp-import>=2.1",
+ "markdown-callouts>=0.4",
+ "markdown-exec>=1.8",
+ "mkdocstrings[python]>=0.29",
+ # YORE: EOL 3.10: Remove line.
+ "tomli>=2.0; python_version < '3.11'",
+ "zensical>=0.0.21",
+]
+
+[tool.uv]
+default-groups = ["maintain", "ci", "docs"]
diff --git a/scripts/gen_credits.py b/scripts/gen_credits.py
index 27f94d67..e8712895 100644
--- a/scripts/gen_credits.py
+++ b/scripts/gen_credits.py
@@ -1,36 +1,34 @@
-"""Script to generate the project's credits."""
+# Script to generate the project's credits.
from __future__ import annotations
-import os
import sys
from collections import defaultdict
+from collections.abc import Iterable
from importlib.metadata import distributions
from itertools import chain
from pathlib import Path
from textwrap import dedent
-from typing import Dict, Iterable, Union
from jinja2 import StrictUndefined
from jinja2.sandbox import SandboxedEnvironment
from packaging.requirements import Requirement
-# TODO: Remove once support for Python 3.10 is dropped.
+# YORE: EOL 3.10: Replace block with line 2.
if sys.version_info >= (3, 11):
import tomllib
else:
import tomli as tomllib
-project_dir = Path(os.getenv("MKDOCS_CONFIG_DIR", "."))
+project_dir = Path.cwd()
with project_dir.joinpath("pyproject.toml").open("rb") as pyproject_file:
pyproject = tomllib.load(pyproject_file)
project = pyproject["project"]
project_name = project["name"]
-with project_dir.joinpath("devdeps.txt").open() as devdeps_file:
- devdeps = [line.strip() for line in devdeps_file if not line.startswith("-e")]
+devdeps = [dep for group in pyproject["dependency-groups"].values() for dep in group if not dep.startswith("-e")]
-PackageMetadata = Dict[str, Union[str, Iterable[str]]]
-Metadata = Dict[str, PackageMetadata]
+PackageMetadata = dict[str, str | Iterable[str]]
+Metadata = dict[str, PackageMetadata]
def _merge_fields(metadata: dict) -> PackageMetadata:
@@ -47,7 +45,7 @@ def _norm_name(name: str) -> str:
return name.replace("_", "-").replace(".", "-").lower()
-def _requirements(deps: list[str]) -> dict[str, Requirement]:
+def _requirements(deps: Iterable[str]) -> dict[str, Requirement]:
return {_norm_name((req := Requirement(dep)).name): req for dep in deps}
@@ -63,8 +61,8 @@ def _extra_marker(req: Requirement) -> str | None:
def _get_metadata() -> Metadata:
metadata = {}
for pkg in distributions():
- name = _norm_name(pkg.name) # type: ignore[attr-defined,unused-ignore]
- metadata[name] = _merge_fields(pkg.metadata) # type: ignore[arg-type]
+ name = _norm_name(pkg.name)
+ metadata[name] = _merge_fields(pkg.metadata) # ty: ignore[invalid-argument-type]
metadata[name]["spec"] = set()
metadata[name]["extras"] = set()
metadata[name].setdefault("summary", "")
@@ -77,10 +75,11 @@ def _set_license(metadata: PackageMetadata) -> None:
license_name = license_field if isinstance(license_field, str) else " + ".join(license_field)
check_classifiers = license_name in ("UNKNOWN", "Dual License", "") or license_name.count("\n")
if check_classifiers:
- license_names = []
- for classifier in metadata["classifier"]:
- if classifier.startswith("License ::"):
- license_names.append(classifier.rsplit("::", 1)[1].strip())
+ license_names = [
+ classifier.rsplit("::", 1)[1].strip()
+ for classifier in metadata["classifier"]
+ if classifier.startswith("License ::")
+ ]
license_name = " + ".join(license_names)
metadata["license"] = license_name or "?"
@@ -88,10 +87,10 @@ def _set_license(metadata: PackageMetadata) -> None:
def _get_deps(base_deps: dict[str, Requirement], metadata: Metadata) -> Metadata:
deps = {}
for dep_name, dep_req in base_deps.items():
- if dep_name not in metadata:
+ if dep_name not in metadata or dep_name == "mkdocstrings":
continue
- metadata[dep_name]["spec"] |= {str(spec) for spec in dep_req.specifier} # type: ignore[operator]
- metadata[dep_name]["extras"] |= dep_req.extras # type: ignore[operator]
+ metadata[dep_name]["spec"] |= {str(spec) for spec in dep_req.specifier} # ty: ignore[unsupported-operator]
+ metadata[dep_name]["extras"] |= dep_req.extras # ty: ignore[unsupported-operator]
deps[dep_name] = metadata[dep_name]
again = True
@@ -109,7 +108,7 @@ def _get_deps(base_deps: dict[str, Requirement], metadata: Metadata) -> Metadata
and dep_name != project["name"]
and (not extra_marker or extra_marker in deps[pkg_name]["extras"])
):
- metadata[dep_name]["spec"] |= {str(spec) for spec in requirement.specifier} # type: ignore[operator]
+ metadata[dep_name]["spec"] |= {str(spec) for spec in requirement.specifier} # ty: ignore[unsupported-operator]
deps[dep_name] = metadata[dep_name]
again = True
@@ -121,7 +120,7 @@ def _render_credits() -> str:
dev_dependencies = _get_deps(_requirements(devdeps), metadata)
prod_dependencies = _get_deps(
_requirements(
- chain( # type: ignore[arg-type]
+ chain(
project.get("dependencies", []),
chain(*project.get("optional-dependencies", {}).values()),
),
@@ -131,8 +130,8 @@ def _render_credits() -> str:
template_data = {
"project_name": project_name,
- "prod_dependencies": sorted(prod_dependencies.values(), key=lambda dep: str(dep["name"])),
- "dev_dependencies": sorted(dev_dependencies.values(), key=lambda dep: str(dep["name"])),
+ "prod_dependencies": sorted(prod_dependencies.values(), key=lambda dep: str(dep["name"]).lower()),
+ "dev_dependencies": sorted(dev_dependencies.values(), key=lambda dep: str(dep["name"]).lower()),
"more_credits": "http://pawamoy.github.io/credits/",
}
template_text = dedent(
diff --git a/scripts/gen_ref_nav.py b/scripts/gen_ref_nav.py
deleted file mode 100644
index 9565765e..00000000
--- a/scripts/gen_ref_nav.py
+++ /dev/null
@@ -1,37 +0,0 @@
-"""Generate the code reference pages and navigation."""
-
-from pathlib import Path
-
-import mkdocs_gen_files
-
-nav = mkdocs_gen_files.Nav()
-mod_symbol = '#{1,6} *|)::: ?(?P.+?) *$", flags=re.MULTILINE)
+ """The regular expression to match our autodoc instructions."""
+
+ def __init__(
+ self,
+ md: Markdown,
+ *,
+ handlers: Handlers,
+ autorefs: AutorefsPlugin,
+ ) -> None:
+ """Initialize the object.
+
+ Arguments:
+ md: A `markdown.Markdown` instance.
+ handlers: The handlers container.
+ autorefs: The autorefs plugin instance.
+ """
+ super().__init__(parser=md.parser)
+ self.md = md
+ """The Markdown instance."""
+ self._handlers = handlers
+ self._autorefs = autorefs
+ self._updated_envs: set = set()
+
+ def test(self, parent: Element, block: str) -> bool: # noqa: ARG002
+ """Match our autodoc instructions.
+
+ Arguments:
+ parent: The parent element in the XML tree.
+ block: The block to be tested.
+
+ Returns:
+ Whether this block should be processed or not.
+ """
+ return bool(self.regex.search(block))
+
+ def run(self, parent: Element, blocks: MutableSequence[str]) -> None:
+ """Run code on the matched blocks.
+
+ The identifier and configuration lines are retrieved from a matched block
+ and used to collect and render an object.
+
+ Arguments:
+ parent: The parent element in the XML tree.
+ blocks: The rest of the blocks to be processed.
+ """
+ block = blocks.pop(0)
+ match = self.regex.search(block)
+
+ if match:
+ if match.start() > 0:
+ self.parser.parseBlocks(parent, [block[: match.start()]])
+ # removes the first line
+ block = block[match.end() :]
+
+ block, the_rest = self.detab(block)
+
+ if not block and blocks and blocks[0].startswith((" handler:", " options:")):
+ # YAML options were separated from the `:::` line by a blank line.
+ block = blocks.pop(0)
+
+ if match:
+ identifier = match["name"]
+ heading_level = match["heading"].count("#")
+ _logger.debug("Matched '::: %s'", identifier)
+
+ html, handler, _ = self._process_block(identifier, block, heading_level)
+ el = Element("div", {"class": "mkdocstrings"})
+ # The final HTML is inserted as opaque to subsequent processing, and only revealed at the end.
+ el.text = self.md.htmlStash.store(html)
+
+ if handler.outer_layer:
+ self._process_headings(handler, el)
+
+ parent.append(el)
+
+ if the_rest:
+ # This block contained unindented line(s) after the first indented
+ # line. Insert these lines as the first block of the master blocks
+ # list for future processing.
+ blocks.insert(0, the_rest)
+
+ def _process_block(
+ self,
+ identifier: str,
+ yaml_block: str,
+ heading_level: int = 0,
+ ) -> tuple[str, BaseHandler, CollectorItem]:
+ """Process an autodoc block.
+
+ Arguments:
+ identifier: The identifier of the object to collect and render.
+ yaml_block: The YAML configuration.
+ heading_level: Suggested level of the heading to insert (0 to ignore).
+
+ Raises:
+ PluginError: When something wrong happened during collection.
+ TemplateNotFound: When a template used for rendering could not be found.
+
+ Returns:
+ Rendered HTML, the handler that was used, and the collected item.
+ """
+ local_config = yaml.safe_load(yaml_block) or {}
+ handler_name = self._handlers.get_handler_name(local_config)
+
+ _logger.debug("Using handler '%s'", handler_name)
+ handler = self._handlers.get_handler(handler_name)
+
+ local_options = local_config.get("options", {})
+ if heading_level:
+ # Heading level obtained from Markdown (`##`) takes precedence.
+ local_options["heading_level"] = heading_level
+
+ options = handler.get_options(local_options)
+
+ _logger.debug("Collecting data")
+ try:
+ data: CollectorItem = handler.collect(identifier, options)
+ except CollectionError as exception:
+ _logger.error("%s", exception) # noqa: TRY400
+ raise PluginError(f"Could not collect '{identifier}'") from exception
+
+ if handler_name not in self._updated_envs: # We haven't seen this handler before on this document.
+ _logger.debug("Updating handler's rendering env")
+ handler._update_env(self.md, config=self._handlers._tool_config)
+ self._updated_envs.add(handler_name)
+
+ _logger.debug("Rendering templates")
+ if "locale" in signature(handler.render).parameters:
+ render = partial(handler.render, locale=self._handlers._locale)
+ else:
+ render = handler.render
+ try:
+ rendered = render(data, options)
+ except TemplateNotFound as exc:
+ _logger.error( # noqa: TRY400
+ "Template '%s' not found for '%s' handler and theme '%s'.",
+ exc.name,
+ handler_name,
+ self._handlers._theme,
+ )
+ raise
+
+ return rendered, handler, data
+
+ def _process_headings(self, handler: BaseHandler, element: Element) -> None:
+ # We're in the outer handler layer, as well as the outer extension layer.
+ #
+ # The "handler layer" tracks the nesting of the autodoc blocks, which can appear in docstrings.
+ #
+ # - Render ::: Object1 # Outer handler layer
+ # - Render Object1's docstring # Outer handler layer
+ # - Docstring renders ::: Object2 # Inner handler layers
+ # - etc. # Inner handler layers
+ #
+ # The "extension layer" tracks whether we're converting an autodoc instruction
+ # or nested content within it, like docstrings. Markdown conversion within Markdown conversion.
+ #
+ # - Render ::: Object1 # Outer extension layer
+ # - Render Object1's docstring # Inner extension layer
+ #
+ # The generated HTML was just stashed, and the `toc` extension won't be able to see headings.
+ # We need to duplicate the headings directly, just so `toc` can pick them up,
+ # otherwise they wouldn't appear in the final table of contents.
+ #
+ # These headings are generated by the `BaseHandler.do_heading` method (Jinja filter),
+ # which runs in the inner extension layer, and not in the outer one where we are now.
+ headings = handler.get_headings()
+ element.extend(headings)
+ # These duplicated headings will later be removed by our `_HeadingsPostProcessor` processor,
+ # which runs right after `toc` (see `MkdocstringsExtension.extendMarkdown`).
+ #
+ # If we were in an inner handler layer, we wouldn't do any of this
+ # and would just let headings bubble up to the outer handler layer.
+
+ if (page := self._autorefs.current_page) is None:
+ return
+
+ for heading in headings:
+ rendered_id = heading.attrib["id"]
+
+ skip_inventory = "data-skip-inventory" in heading.attrib
+ if skip_inventory:
+ _logger.debug(
+ "Skipping heading with id %r because data-skip-inventory is present",
+ rendered_id,
+ )
+ continue
+
+ # The title is registered to be used as tooltip by autorefs.
+ self._autorefs.register_anchor(page, rendered_id, title=heading.text, primary=True)
+
+ # Register all identifiers for this object
+ # both in the autorefs plugin and in the inventory.
+ aliases: tuple[str, ...]
+ aliases = handler.get_aliases(rendered_id)
+
+ for alias in aliases:
+ if alias != rendered_id:
+ self._autorefs.register_anchor(page, alias, rendered_id, primary=False)
+
+ if "data-role" in heading.attrib:
+ self._handlers.inventory.register(
+ name=rendered_id,
+ domain=handler.domain,
+ role=heading.attrib["data-role"],
+ priority=1, # Register with standard priority.
+ uri=f"{page.url}#{rendered_id}",
+ )
+ for alias in aliases:
+ if alias not in self._handlers.inventory:
+ self._handlers.inventory.register(
+ name=alias,
+ domain=handler.domain,
+ role=heading.attrib["data-role"],
+ priority=2, # Register with lower priority.
+ uri=f"{page.url}#{rendered_id}",
+ )
+
+
+class _HeadingsPostProcessor(Treeprocessor):
+ def run(self, root: Element) -> None:
+ self._remove_duplicated_headings(root)
+
+ def _remove_duplicated_headings(self, parent: Element) -> None:
+ carry_text = ""
+ for el in reversed(parent): # Reversed mainly for the ability to mutate during iteration.
+ if el.tag == "div" and el.get("class") == "mkdocstrings":
+ # Delete the duplicated headings along with their container, but keep the text (i.e. the actual HTML).
+ carry_text = (el.text or "") + carry_text
+ parent.remove(el)
+ else:
+ if carry_text:
+ el.tail = (el.tail or "") + carry_text
+ carry_text = ""
+ self._remove_duplicated_headings(el)
+
+ if carry_text:
+ parent.text = (parent.text or "") + carry_text
+
+
+class _TocLabelsTreeProcessor(Treeprocessor):
+ def run(self, root: Element) -> None: # noqa: ARG002
+ self._override_toc_labels(self.md.toc_tokens) # ty: ignore[unresolved-attribute]
+
+ def _override_toc_labels(self, tokens: list[dict[str, Any]]) -> None:
+ for token in tokens:
+ if (label := token.get("data-toc-label")) and token["name"] != label:
+ token["name"] = label
+ self._override_toc_labels(token["children"])
+
+
+class MkdocstringsExtension(Extension):
+ """Our Markdown extension.
+
+ It cannot work outside of `mkdocstrings`.
+ """
+
+ def __init__(
+ self,
+ handlers: Handlers,
+ autorefs: AutorefsPlugin,
+ *,
+ autorefs_extension: bool = False,
+ **kwargs: Any,
+ ) -> None:
+ """Initialize the object.
+
+ Arguments:
+ handlers: The handlers container.
+ autorefs: The autorefs plugin instance.
+ autorefs_extension: Whether the autorefs extension must be registered.
+ **kwargs: Keyword arguments used by `markdown.extensions.Extension`.
+ """
+ super().__init__(**kwargs)
+ self._handlers = handlers
+ self._autorefs = autorefs
+ self._autorefs_extension = autorefs_extension
+
+ def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name)
+ """Register the extension.
+
+ Add an instance of our [`AutoDocProcessor`][mkdocstrings.AutoDocProcessor] to the Markdown parser.
+
+ Arguments:
+ md: A `markdown.Markdown` instance.
+ """
+ md.registerExtension(self)
+
+ # Zensical integration: get the current page from the Zensical-specific preprocessor.
+ if "zensical_current_page" in md.preprocessors:
+ self._autorefs.current_page = md.preprocessors["zensical_current_page"]
+
+ md.parser.blockprocessors.register(
+ AutoDocProcessor(md, handlers=self._handlers, autorefs=self._autorefs),
+ "mkdocstrings",
+ priority=75, # Right before markdown.blockprocessors.HashHeaderProcessor
+ )
+ md.treeprocessors.register(
+ _HeadingsPostProcessor(md),
+ "mkdocstrings_post_headings",
+ priority=4, # Right after 'toc'.
+ )
+ md.treeprocessors.register(
+ _TocLabelsTreeProcessor(md),
+ "mkdocstrings_post_toc_labels",
+ priority=4, # Right after 'toc'.
+ )
+
+ if self._autorefs_extension:
+ AutorefsExtension(self._autorefs).extendMarkdown(md)
+
+
+# -----------------------------------------------------------------------------
+# The following is only used by Zensical. The goal is to provide temporary
+# compatibility for users migrating from MkDocs (and Material for MkDocs)
+# to Zensical. When detecting the use of the mkdocstrings plugin in mkdocs.yml,
+# Zensical will add the mkdocstrings extension to its Markdown extensions.
+
+_default_config: dict[str, Any] = {
+ "default_handler": "python",
+ "handlers": {},
+ "custom_templates": None,
+ "locale": "en",
+ "enable_inventory": True,
+ "enabled": True,
+}
+
+
+def _split_configs(
+ markdown_extensions: list[str | dict[str, dict[str, Any]] | Extension],
+) -> tuple[list[str | Extension], dict[str, dict[str, Any]]]:
+ # Split markdown extensions and their configs from mkdocs.yml
+ mdx: list[str | Extension] = []
+ mdx_config: dict[str, dict[str, Any]] = {}
+ for item in markdown_extensions:
+ if isinstance(item, (str, Extension)):
+ mdx.append(item)
+ elif isinstance(item, dict):
+ for key, value in item.items():
+ mdx.append(key)
+ mdx_config[key] = value
+ break # Only one item per dict
+ return mdx, mdx_config
+
+
+class _ToolConfig:
+ def __init__(self, config_file_path: str | None = None) -> None:
+ self.config_file_path = config_file_path
+
+
+_AUTOREFS = None
+_HANDLERS = None
+
+
+def makeExtension( # noqa: N802
+ *,
+ default_handler: str | None = None,
+ inventory_project: str | None = None,
+ inventory_version: str | None = None,
+ handlers: dict[str, dict] | None = None,
+ custom_templates: str | None = None,
+ markdown_extensions: list[str | dict | Extension] | None = None,
+ locale: str | None = None,
+ config_file_path: str | None = None,
+) -> MkdocstringsExtension:
+ """Create the extension instance.
+
+ We only support this function being used by Zensical.
+ Consider this function private API.
+ """
+ global _AUTOREFS # noqa: PLW0603
+ if _AUTOREFS is None:
+ _AUTOREFS = AutorefsPlugin()
+ _AUTOREFS.config = AutorefsConfig() # ty:ignore[invalid-assignment]
+ _AUTOREFS.config.resolve_closest = True
+ _AUTOREFS.config.link_titles = "auto"
+ _AUTOREFS.config.strip_title_tags = "auto"
+ _AUTOREFS.scan_toc = True
+ _AUTOREFS._link_titles = "external"
+ _AUTOREFS._strip_title_tags = False
+
+ global _HANDLERS # noqa: PLW0603
+ if _HANDLERS is None:
+ mdx, mdx_config = _split_configs(markdown_extensions or [])
+ tool_config = _ToolConfig(config_file_path=config_file_path)
+ mdx.append(AutorefsExtension(_AUTOREFS))
+ _HANDLERS = Handlers(
+ theme="material",
+ default=default_handler or _default_config["default_handler"],
+ inventory_project=inventory_project or "Project",
+ inventory_version=inventory_version or "0.0.0",
+ handlers_config=handlers or _default_config["handlers"],
+ custom_templates=custom_templates or _default_config["custom_templates"],
+ mdx=mdx,
+ mdx_config=mdx_config,
+ locale=locale or _default_config["locale"],
+ tool_config=tool_config,
+ )
+
+ _HANDLERS._download_inventories()
+ register = _AUTOREFS.register_url
+ for identifier, url in _HANDLERS._yield_inventory_items():
+ register(identifier, url)
+
+ return MkdocstringsExtension(
+ handlers=_HANDLERS,
+ autorefs=_AUTOREFS,
+ autorefs_extension=True,
+ )
+
+
+def _reset() -> None:
+ global _AUTOREFS, _HANDLERS # noqa: PLW0603
+ _AUTOREFS = None
+ _HANDLERS = None
+
+
+def _get_autorefs() -> dict[str, Any]:
+ if _AUTOREFS:
+ return {
+ "primary": _AUTOREFS._primary_url_map,
+ "secondary": _AUTOREFS._secondary_url_map,
+ "inventory": _AUTOREFS._abs_url_map,
+ "titles": _AUTOREFS._title_map,
+ }
+ return {}
+
+
+def _get_inventory() -> bytes:
+ if _HANDLERS:
+ return _HANDLERS.inventory.format_sphinx()
+ return b""
diff --git a/src/mkdocstrings/_internal/handlers/__init__.py b/src/mkdocstrings/_internal/handlers/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/mkdocstrings/_internal/handlers/base.py b/src/mkdocstrings/_internal/handlers/base.py
new file mode 100644
index 00000000..799c4499
--- /dev/null
+++ b/src/mkdocstrings/_internal/handlers/base.py
@@ -0,0 +1,666 @@
+# Base module for handlers.
+#
+# This module contains the base classes for implementing handlers.
+
+from __future__ import annotations
+
+import datetime
+import importlib
+import ssl
+from concurrent import futures
+from importlib.metadata import entry_points
+from io import BytesIO
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, cast
+from warnings import warn
+from xml.etree.ElementTree import Element, tostring
+
+from jinja2 import Environment, FileSystemLoader
+from markdown import Markdown
+from markupsafe import Markup
+from mkdocs.utils.cache import download_and_cache_url
+from mkdocs_autorefs import AutorefsInlineProcessor, BacklinksTreeProcessor
+
+from mkdocstrings._internal.download import _download_url_with_gz
+from mkdocstrings._internal.handlers.rendering import (
+ HeadingShiftingTreeprocessor,
+ Highlighter,
+ IdPrependingTreeprocessor,
+ MkdocstringsInnerExtension,
+ ParagraphStrippingTreeprocessor,
+)
+from mkdocstrings._internal.inventory import Inventory
+from mkdocstrings._internal.loggers import get_logger, get_template_logger
+
+if TYPE_CHECKING:
+ from collections.abc import Iterable, Iterator, Mapping, Sequence
+
+ from markdown import Extension
+ from markdown.extensions.toc import TocTreeprocessor
+ from mkdocs_autorefs import AutorefsHookInterface, Backlink
+
+_logger = get_logger("mkdocstrings")
+
+CollectorItem = Any
+"""The type of the item returned by the `collect` method of a handler."""
+HandlerConfig = Any
+"""The type of the configuration of a handler."""
+HandlerOptions = Any
+"""The type of the options passed to a handler."""
+
+
+# Autodoc instructions can appear in nested Markdown,
+# so we need to keep track of the Markdown conversion layer we're in.
+# Since any handler can be called from any Markdown conversion layer,
+# we need to keep track of the layer globally.
+# This global variable is incremented/decremented in `do_convert_markdown`,
+# and used in `outer_layer`.
+_markdown_conversion_layer: int = 0
+
+
+class CollectionError(Exception):
+ """An exception raised when some collection of data failed."""
+
+
+class ThemeNotSupported(Exception): # noqa: N818
+ """An exception raised to tell a theme is not supported."""
+
+
+def do_any(seq: Sequence, attribute: str | None = None) -> bool:
+ """Check if at least one of the item in the sequence evaluates to true.
+
+ The `any` builtin as a filter for Jinja templates.
+
+ Arguments:
+ seq: An iterable object.
+ attribute: The attribute name to use on each object of the iterable.
+
+ Returns:
+ A boolean telling if any object of the iterable evaluated to True.
+ """
+ if attribute is None:
+ return any(seq)
+ return any(_[attribute] for _ in seq)
+
+
+class BaseHandler:
+ """The base handler class.
+
+ Inherit from this class to implement a handler.
+
+ You will have to implement the `collect` and `render` methods.
+ You can also implement the `teardown` method,
+ and override the `update_env` method, to add more filters to the Jinja environment,
+ making them available in your Jinja templates.
+
+ To define a fallback theme, add a `fallback_theme` class-variable.
+ To add custom CSS, add an `extra_css` variable or create an 'style.css' file beside the templates.
+ """
+
+ name: ClassVar[str]
+ """The handler's name, for example "python"."""
+
+ domain: ClassVar[str]
+ """The handler's domain, used to register objects in the inventory, for example "py"."""
+
+ enable_inventory: ClassVar[bool] = False
+ """Whether the inventory creation is enabled."""
+
+ fallback_theme: ClassVar[str] = ""
+ """Fallback theme to use when a template isn't found in the configured theme."""
+
+ extra_css: str = ""
+ """Extra CSS."""
+
+ def __init__(
+ self,
+ *,
+ theme: str,
+ custom_templates: str | None,
+ mdx: Sequence[str | Extension],
+ mdx_config: Mapping[str, Any],
+ ) -> None:
+ """Initialize the object.
+
+ If the given theme is not supported (it does not exist), it will look for a `fallback_theme` attribute
+ in `self` to use as a fallback theme.
+
+ Keyword Arguments:
+ theme (str): The theme to use.
+ custom_templates (str | None): The path to custom templates.
+ mdx (list[str | Extension]): A list of Markdown extensions to use.
+ mdx_config (Mapping[str, Mapping[str, Any]]): Configuration for the Markdown extensions.
+ """
+ self.theme = theme
+ """The selected theme."""
+ self.custom_templates = custom_templates
+ """The path to custom templates."""
+ self.mdx = mdx
+ """The Markdown extensions to use."""
+ self.mdx_config = mdx_config
+ """The configuration for the Markdown extensions."""
+ self._md: Markdown | None = None
+ self._headings: list[Element] = []
+
+ paths = []
+
+ # add selected theme templates
+ themes_dir = self.get_templates_dir(self.name)
+ paths.append(themes_dir / self.theme)
+
+ # add extended theme templates
+ extended_templates_dirs = self.get_extended_templates_dirs(self.name)
+ paths.extend(templates_dir / self.theme for templates_dir in extended_templates_dirs)
+
+ # add fallback theme templates
+ if self.fallback_theme and self.fallback_theme != self.theme:
+ paths.append(themes_dir / self.fallback_theme)
+
+ # add fallback theme of extended templates
+ paths.extend(templates_dir / self.fallback_theme for templates_dir in extended_templates_dirs)
+
+ for path in paths:
+ css_path = path / "style.css"
+ if css_path.is_file():
+ self.extra_css += "\n" + css_path.read_text(encoding="utf-8")
+ break
+
+ if self.custom_templates is not None:
+ paths.insert(0, Path(self.custom_templates) / self.name / self.theme)
+
+ self.env = Environment(
+ autoescape=True,
+ loader=FileSystemLoader(paths),
+ auto_reload=False, # Editing a template in the middle of a build is not useful.
+ )
+ """The Jinja environment."""
+
+ self.env.filters["convert_markdown"] = self.do_convert_markdown
+ self.env.filters["heading"] = self.do_heading
+ self.env.filters["any"] = do_any
+ self.env.globals["log"] = get_template_logger(self.name) # ty:ignore[invalid-assignment]
+
+ @property
+ def md(self) -> Markdown:
+ """The Markdown instance.
+
+ Raises:
+ RuntimeError: When the Markdown instance is not set yet.
+ """
+ if self._md is None:
+ raise RuntimeError("Markdown instance not set yet")
+ return self._md
+
+ def get_inventory_urls(self) -> list[tuple[str, dict[str, Any]]]:
+ """Return the URLs (and configuration options) of the inventory files to download."""
+ return []
+
+ @classmethod
+ def load_inventory(
+ cls,
+ in_file: BinaryIO, # noqa: ARG003
+ url: str, # noqa: ARG003
+ base_url: str | None = None, # noqa: ARG003
+ **kwargs: Any, # noqa: ARG003
+ ) -> Iterator[tuple[str, str]]:
+ """Yield items and their URLs from an inventory file streamed from `in_file`.
+
+ Arguments:
+ in_file: The binary file-like object to read the inventory from.
+ url: The URL that this file is being streamed from (used to guess `base_url`).
+ base_url: The URL that this inventory's sub-paths are relative to.
+ **kwargs: Ignore additional arguments passed from the config.
+
+ Yields:
+ Tuples of (item identifier, item URL).
+ """
+ yield from ()
+
+ def get_options(self, local_options: Mapping[str, Any]) -> HandlerOptions:
+ """Get combined options.
+
+ 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 `collect` and `render`.
+
+ Arguments:
+ local_options: The local options.
+
+ Returns:
+ The combined options.
+ """
+ return local_options
+
+ def collect(self, identifier: str, options: HandlerOptions) -> CollectorItem:
+ """Collect data given an identifier and user configuration.
+
+ 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.
+
+ Arguments:
+ identifier: 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.
+ options: The final configuration options.
+
+ Returns:
+ Anything you want, as long as you can feed it to the handler's `render` method.
+ """
+ raise NotImplementedError
+
+ def render(self, data: CollectorItem, options: HandlerOptions, *, locale: str | None = None) -> str:
+ """Render a template using provided data and configuration options.
+
+ Arguments:
+ data: The collected data to render.
+ options: The final configuration options.
+ locale: The locale to use for translations, if any.
+
+ Returns:
+ The rendered template as HTML.
+ """
+ raise NotImplementedError
+
+ def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]], *, locale: str | None = None) -> str: # noqa: ARG002
+ """Render backlinks.
+
+ Parameters:
+ backlinks: A mapping of identifiers to backlinks.
+ locale: The locale to use for translations, if any.
+
+ Returns:
+ The rendered backlinks as HTML.
+ """
+ return ""
+
+ def teardown(self) -> None:
+ """Teardown the handler.
+
+ This method should be implemented to, for example, terminate a subprocess
+ that was started when creating the handler instance.
+ """
+
+ def get_templates_dir(self, handler: str | None = None) -> Path:
+ """Return the path to the handler's templates directory.
+
+ Override to customize how the templates directory is found.
+
+ Arguments:
+ handler: The name of the handler to get the templates directory of.
+
+ Raises:
+ ModuleNotFoundError: When no such handler is installed.
+ FileNotFoundError: When the templates directory cannot be found.
+
+ Returns:
+ The templates directory path.
+ """
+ handler = handler or self.name
+ try:
+ import mkdocstrings_handlers # noqa: PLC0415
+ except ModuleNotFoundError as error:
+ raise ModuleNotFoundError(f"Handler '{handler}' not found, is it installed?") from error
+
+ for path in mkdocstrings_handlers.__path__:
+ theme_path = Path(path, handler, "templates")
+ if theme_path.exists():
+ return theme_path
+
+ raise FileNotFoundError(f"Can't find 'templates' folder for handler '{handler}'")
+
+ def get_extended_templates_dirs(self, handler: str) -> list[Path]:
+ """Load template extensions for the given handler, return their templates directories.
+
+ Arguments:
+ handler: The name of the handler to get the extended templates directory of.
+
+ Returns:
+ The extensions templates directories.
+ """
+ discovered_extensions = entry_points(group=f"mkdocstrings.{handler}.templates")
+ return [extension.load()() for extension in discovered_extensions]
+
+ def get_aliases(self, identifier: str) -> tuple[str, ...]: # noqa: ARG002
+ """Return the possible aliases for a given identifier.
+
+ Arguments:
+ identifier: The identifier to get the aliases of.
+
+ Returns:
+ A tuple of strings - aliases.
+ """
+ return ()
+
+ @property
+ def outer_layer(self) -> bool:
+ """Whether we're in the outer Markdown conversion layer."""
+ return _markdown_conversion_layer == 0
+
+ def do_convert_markdown(
+ self,
+ text: str,
+ heading_level: int,
+ html_id: str = "",
+ *,
+ strip_paragraph: bool = False,
+ autoref_hook: AutorefsHookInterface | None = None,
+ ) -> Markup:
+ """Render Markdown text; for use inside templates.
+
+ Arguments:
+ text: The text to convert.
+ heading_level: The base heading level to start all Markdown headings from.
+ html_id: The HTML id of the element that's considered the parent of this element.
+ strip_paragraph: Whether to exclude the `` tag from around the whole output.
+
+ Returns:
+ An HTML string.
+ """
+ global _markdown_conversion_layer # noqa: PLW0603
+ _markdown_conversion_layer += 1
+ treeprocessors = self.md.treeprocessors
+ treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level
+ treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--"
+ treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph
+ if BacklinksTreeProcessor.name in treeprocessors:
+ treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id
+ if autoref_hook and AutorefsInlineProcessor.name in self.md.inlinePatterns:
+ self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook # ty: ignore[unresolved-attribute]
+
+ try:
+ return Markup(self.md.convert(text))
+ finally:
+ treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0
+ treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""
+ treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False
+ if BacklinksTreeProcessor.name in treeprocessors:
+ treeprocessors[BacklinksTreeProcessor.name].initial_id = None
+ if AutorefsInlineProcessor.name in self.md.inlinePatterns:
+ self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = None
+ self.md.reset()
+ _markdown_conversion_layer -= 1
+
+ def do_heading(
+ self,
+ content: Markup,
+ heading_level: int,
+ *,
+ role: str | None = None,
+ hidden: bool = False,
+ toc_label: str | None = None,
+ skip_inventory: bool = False,
+ **attributes: str,
+ ) -> Markup:
+ """Render an HTML heading and register it for the table of contents. For use inside templates.
+
+ Arguments:
+ content: The HTML within the heading.
+ heading_level: The level of heading (e.g. 3 -> `h3`).
+ role: An optional role for the object bound to this heading.
+ hidden: If True, only register it for the table of contents, don't render anything.
+ toc_label: The title to use in the table of contents ('data-toc-label' attribute).
+ skip_inventory: Flag element to not be registered in the inventory (by setting a `data-skip-inventory` attribute).
+ **attributes: Any extra HTML attributes of the heading.
+
+ Returns:
+ An HTML string.
+ """
+ # Produce a heading element that will be used later, in `AutoDocProcessor.run`, to:
+ # - register it in the ToC: right now we're in the inner Markdown conversion layer,
+ # so we have to bubble up the information to the outer Markdown conversion layer,
+ # for the ToC extension to pick it up.
+ # - register it in autorefs: right now we don't know what page is being rendered,
+ # so we bubble up the information again to where autorefs knows the page,
+ # and can correctly register the heading anchor (id) to its full URL.
+ # - register it in the objects inventory: same as for autorefs,
+ # we don't know the page here, or the handler (and its domain),
+ # so we bubble up the information to where the mkdocstrings extension knows that.
+ el = Element(f"h{heading_level}", attributes)
+ if toc_label is None:
+ toc_label = content.unescape() if isinstance(content, Markup) else content
+ el.set("data-toc-label", toc_label)
+ if skip_inventory:
+ el.set("data-skip-inventory", "true")
+ if role:
+ el.set("data-role", role)
+ if content:
+ el.text = str(content).strip()
+ self._headings.append(el)
+
+ if hidden:
+ return Markup('').format(attributes["id"])
+
+ # Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.
+ # Start with a heading that has just attributes (no text), and add a placeholder into it.
+ el = Element(f"h{heading_level}", attributes)
+ el.append(Element("mkdocstrings-placeholder"))
+ # Tell the inner 'toc' extension to make its additions if configured so.
+ toc = cast("TocTreeprocessor", self.md.treeprocessors["toc"])
+ if toc.use_anchors:
+ toc.add_anchor(el, attributes["id"])
+ if toc.use_permalinks:
+ toc.add_permalink(el, attributes["id"])
+
+ # The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle
+ # of the heading with a placeholder that can never occur (text can't directly contain angle brackets).
+ # Now this HTML wrapper can be "filled" by replacing the placeholder.
+ html_with_placeholder = tostring(el, encoding="unicode")
+ assert ( # noqa: S101
+ html_with_placeholder.count("
` with `shift_by = 3` becomes ``."""
@@ -205,7 +210,8 @@ def __init__(self, md: Markdown, shift_by: int):
super().__init__(md)
self.shift_by = shift_by
- def run(self, root: Element) -> None: # noqa: D102 (ignore missing docstring)
+ def run(self, root: Element) -> None:
+ """Shift the levels of all headings in the document."""
if not self.shift_by:
return
for el in root.iter():
@@ -219,8 +225,11 @@ def run(self, root: Element) -> None: # noqa: D102 (ignore missing docstring)
class _HeadingReportingTreeprocessor(Treeprocessor):
"""Records the heading elements encountered in the document."""
- name = "mkdocstrings_headings_list"
- regex = re.compile(r"[Hh][1-6]")
+ name: str = "mkdocstrings_headings_list"
+ """The name of the treeprocessor."""
+
+ regex: re.Pattern = re.compile(r"[Hh][1-6]")
+ """The regex to match heading tags."""
headings: list[Element]
"""The list (the one passed in the initializer) that is used to record the heading elements (by appending to it)."""
@@ -230,7 +239,8 @@ def __init__(self, md: Markdown, headings: list[Element]):
self.headings = headings
def run(self, root: Element) -> None:
- permalink_class = self.md.treeprocessors["toc"].permalink_class # type: ignore[attr-defined]
+ """Record all heading elements encountered in the document."""
+ permalink_class = self.md.treeprocessors["toc"].permalink_class
for el in root.iter():
if self.regex.fullmatch(el.tag):
el = copy.copy(el) # noqa: PLW2901
@@ -242,14 +252,18 @@ def run(self, root: Element) -> None:
class ParagraphStrippingTreeprocessor(Treeprocessor):
- """Unwraps the
element around the whole output."""
+ """Unwraps the `
` element around the whole output."""
+
+ name: str = "mkdocstrings_strip_paragraph"
+ """The name of the treeprocessor."""
- name = "mkdocstrings_strip_paragraph"
- strip = False
+ strip: bool = False
+ """Whether to strip `
` elements or not."""
- def run(self, root: Element) -> Element | None: # noqa: D102 (ignore missing docstring)
+ def run(self, root: Element) -> Element | None:
+ """Unwrap the root element if it's a single `
` element."""
if self.strip and len(root) == 1 and root[0].tag == "p":
- # Turn the single
element into the root element and inherit its tag name (it's significant!)
+ # Turn the single `
` element into the root element and inherit its tag name (it's significant!)
root[0].tag = root.tag
return root[0]
return None
@@ -266,6 +280,7 @@ def __init__(self, headings: list[Element]):
"""
super().__init__()
self.headings = headings
+ """The list that will be populated with all HTML heading elements encountered in the document."""
def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name)
"""Register the extension.
diff --git a/src/mkdocstrings/inventory.py b/src/mkdocstrings/_internal/inventory.py
similarity index 81%
rename from src/mkdocstrings/inventory.py
rename to src/mkdocstrings/_internal/inventory.py
index f1c8962a..241bbb12 100644
--- a/src/mkdocstrings/inventory.py
+++ b/src/mkdocstrings/_internal/inventory.py
@@ -1,14 +1,17 @@
-"""Module responsible for the objects inventory."""
-
+# Module responsible for the objects inventory.
+#
# Credits to Brian Skinn and the sphobjinv project:
-# https://github.com/bskinn/sphobjinv
+# https://github.com/bskinn/sphobjinv.
from __future__ import annotations
import re
import zlib
from textwrap import dedent
-from typing import BinaryIO, Collection
+from typing import TYPE_CHECKING, BinaryIO, Literal, overload
+
+if TYPE_CHECKING:
+ from collections.abc import Collection
class InventoryItem:
@@ -34,11 +37,17 @@ def __init__(
dispname: The item display name.
"""
self.name: str = name
+ """The item name."""
self.domain: str = domain
+ """The item domain."""
self.role: str = role
+ """The item role."""
self.uri: str = uri
+ """The item URI."""
self.priority: int = priority
+ """The item priority."""
self.dispname: str = dispname or name
+ """The item display name."""
def format_sphinx(self) -> str:
"""Format this item as a Sphinx inventory line.
@@ -55,12 +64,23 @@ def format_sphinx(self) -> str:
return f"{self.name} {self.domain}:{self.role} {self.priority} {uri} {dispname}"
sphinx_item_regex = re.compile(r"^(.+?)\s+(\S+):(\S+)\s+(-?\d+)\s+(\S+)\s*(.*)$")
+ """Regex to parse a Sphinx v2 inventory line."""
+
+ @overload
+ @classmethod
+ def parse_sphinx(cls, line: str, *, return_none: Literal[False]) -> InventoryItem: ...
+ @overload
@classmethod
- def parse_sphinx(cls, line: str) -> InventoryItem:
+ def parse_sphinx(cls, line: str, *, return_none: Literal[True]) -> InventoryItem | None: ...
+
+ @classmethod
+ def parse_sphinx(cls, line: str, *, return_none: bool = False) -> InventoryItem | None:
"""Parse a line from a Sphinx v2 inventory file and return an `InventoryItem` from it."""
match = cls.sphinx_item_regex.search(line)
if not match:
+ if return_none:
+ return None
raise ValueError(line)
name, domain, role, priority, uri, dispname = match.groups()
if uri.endswith("$"):
@@ -86,7 +106,9 @@ def __init__(self, items: list[InventoryItem] | None = None, project: str = "pro
for item in items:
self[item.name] = item
self.project = project
+ """The project name."""
self.version = version
+ """The project version."""
def register(
self,
@@ -155,7 +177,9 @@ def parse_sphinx(cls, in_file: BinaryIO, *, domain_filter: Collection[str] = ())
for _ in range(4):
in_file.readline()
lines = zlib.decompress(in_file.read()).splitlines()
- items = [InventoryItem.parse_sphinx(line.decode("utf8")) for line in lines]
+ items: list[InventoryItem] = [
+ item for line in lines if (item := InventoryItem.parse_sphinx(line.decode("utf8"), return_none=True))
+ ]
if domain_filter:
items = [item for item in items if item.domain in domain_filter]
return cls(items)
diff --git a/src/mkdocstrings/loggers.py b/src/mkdocstrings/_internal/loggers.py
similarity index 53%
rename from src/mkdocstrings/loggers.py
rename to src/mkdocstrings/_internal/loggers.py
index 63502474..6c8817ac 100644
--- a/src/mkdocstrings/loggers.py
+++ b/src/mkdocstrings/_internal/loggers.py
@@ -1,31 +1,49 @@
-"""Logging functions."""
+# Logging functions.
from __future__ import annotations
import logging
from contextlib import suppress
from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, MutableMapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from jinja2 import pass_context
+
+if TYPE_CHECKING:
+ from collections.abc import Callable, MutableMapping, Sequence
+
+ from jinja2.runtime import Context
-try:
- from jinja2 import pass_context
-except ImportError: # TODO: remove once Jinja2 < 3.1 is dropped
- from jinja2 import contextfunction as pass_context # type: ignore[attr-defined,no-redef]
try:
import mkdocstrings_handlers
except ImportError:
TEMPLATES_DIRS: Sequence[Path] = ()
else:
- TEMPLATES_DIRS = tuple(mkdocstrings_handlers.__path__) # type: ignore[arg-type]
+ TEMPLATES_DIRS = tuple(mkdocstrings_handlers.__path__)
+ """The directories where the handler templates are located."""
-if TYPE_CHECKING:
- from jinja2.runtime import Context
+class LoggerAdapter(logging.LoggerAdapter):
+ """A logger adapter to prefix messages.
+ This adapter also adds an additional parameter to logging methods
+ called `once`: if `True`, the message will only be logged once.
-class LoggerAdapter(logging.LoggerAdapter):
- """A logger adapter to prefix messages."""
+ Examples:
+ In Python code:
+
+ >>> logger = get_logger("myplugin")
+ >>> logger.debug("This is a debug message.")
+ >>> logger.info("This is an info message.", once=True)
+
+ In Jinja templates (logger available in context as `log`):
+
+ ```jinja
+ {{ log.debug("This is a debug message.") }}
+ {{ log.info("This is an info message.", once=True) }}
+ ```
+ """
def __init__(self, prefix: str, logger: logging.Logger):
"""Initialize the object.
@@ -36,6 +54,8 @@ def __init__(self, prefix: str, logger: logging.Logger):
"""
super().__init__(logger, {})
self.prefix = prefix
+ """The prefix to insert in front of every message."""
+ self._logged: set[tuple[LoggerAdapter, str]] = set()
def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, Any]:
"""Process the message.
@@ -49,11 +69,32 @@ def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, Any]
"""
return f"{self.prefix}: {msg}", kwargs
+ def log(self, level: int, msg: object, *args: object, **kwargs: object) -> None:
+ """Log a message.
+
+ Arguments:
+ level: The logging level.
+ msg: The message.
+ *args: Additional arguments passed to parent method.
+ **kwargs: Additional keyword arguments passed to parent method.
+ """
+ if kwargs.pop("once", False):
+ if (key := (self, str(msg))) in self._logged:
+ return
+ self._logged.add(key)
+ super().log(level, msg, *args, **kwargs) # ty: ignore[invalid-argument-type]
+
class TemplateLogger:
"""A wrapper class to allow logging in templates.
- Attributes:
+ The logging methods provided by this class all accept
+ two parameters:
+
+ - `msg`: The message to log.
+ - `once`: If `True`, the message will only be logged once.
+
+ Methods:
debug: Function to log a DEBUG message.
info: Function to log an INFO message.
warning: Function to log a WARNING message.
@@ -68,10 +109,36 @@ def __init__(self, logger: LoggerAdapter):
logger: A logger adapter.
"""
self.debug = get_template_logger_function(logger.debug)
+ """Log a DEBUG message."""
self.info = get_template_logger_function(logger.info)
+ """Log an INFO message."""
self.warning = get_template_logger_function(logger.warning)
+ """Log a WARNING message."""
self.error = get_template_logger_function(logger.error)
+ """Log an ERROR message."""
self.critical = get_template_logger_function(logger.critical)
+ """Log a CRITICAL message."""
+
+
+class _Lazy:
+ unset = object()
+
+ def __init__(self, func: Callable, *args: Any, **kwargs: Any):
+ self.func = func
+ self.args = args
+ self.kwargs = kwargs
+ self.result = self.unset
+
+ def __call__(self):
+ if self.result is self.unset:
+ self.result = self.func(*self.args, **self.kwargs)
+ return self.result
+
+ def __str__(self) -> str:
+ return str(self())
+
+ def __repr__(self) -> str:
+ return repr(self())
def get_template_logger_function(logger_func: Callable) -> Callable:
@@ -85,18 +152,18 @@ def get_template_logger_function(logger_func: Callable) -> Callable:
"""
@pass_context
- def wrapper(context: Context, msg: str | None = None) -> str:
+ def wrapper(context: Context, msg: str | None = None, *args: Any, **kwargs: Any) -> str:
"""Log a message.
Arguments:
context: The template context, automatically provided by Jinja.
msg: The message to log.
+ **kwargs: Additional arguments passed to the logger function.
Returns:
An empty string.
"""
- template_path = get_template_path(context)
- logger_func(f"{template_path}: {msg or 'Rendering'}")
+ logger_func(f"%s: {msg or 'Rendering'}", _Lazy(get_template_path, context), *args, **kwargs)
return ""
return wrapper
@@ -136,10 +203,14 @@ def get_logger(name: str) -> LoggerAdapter:
return LoggerAdapter(name.split(".", 1)[0], logger)
-def get_template_logger() -> TemplateLogger:
+def get_template_logger(handler_name: str | None = None) -> TemplateLogger:
"""Return a logger usable in templates.
+ Parameters:
+ handler_name: The name of the handler.
+
Returns:
A template logger.
"""
- return TemplateLogger(get_logger("mkdocstrings.templates"))
+ handler_name = handler_name or "base"
+ return TemplateLogger(get_logger(f"mkdocstrings_handlers.{handler_name}.templates"))
diff --git a/src/mkdocstrings/_internal/plugin.py b/src/mkdocstrings/_internal/plugin.py
new file mode 100644
index 00000000..4f9bd29d
--- /dev/null
+++ b/src/mkdocstrings/_internal/plugin.py
@@ -0,0 +1,298 @@
+# This module contains the "mkdocstrings" plugin for MkDocs.
+#
+# The plugin instantiates a Markdown extension ([`MkdocstringsExtension`][mkdocstrings.MkdocstringsExtension]),
+# and adds it to the list of Markdown extensions used by `mkdocs`
+# during the [`on_config` event hook](https://www.mkdocs.org/user-guide/plugins/#on_config).
+#
+# Once the documentation is built, the [`on_post_build` event hook](https://www.mkdocs.org/user-guide/plugins/#on_post_build)
+# is triggered and calls the [`handlers.teardown()` method][mkdocstrings.Handlers.teardown]. This method is
+# used to teardown the handlers that were instantiated during documentation buildup.
+#
+# Finally, when serving the documentation, it can add directories to watch
+# during the [`on_serve` event hook](https://www.mkdocs.org/user-guide/plugins/#on_serve).
+
+from __future__ import annotations
+
+import os
+import re
+from functools import partial
+from inspect import signature
+from re import Match
+from typing import TYPE_CHECKING, Any
+
+from mkdocs.config import Config
+from mkdocs.config import config_options as opt
+from mkdocs.plugins import BasePlugin, CombinedEvent, event_priority
+from mkdocs.utils import write_file
+from mkdocs_autorefs import AutorefsConfig, AutorefsPlugin
+
+from mkdocstrings._internal.extension import MkdocstringsExtension
+from mkdocstrings._internal.handlers.base import BaseHandler, Handlers
+from mkdocstrings._internal.loggers import get_logger
+
+if TYPE_CHECKING:
+ from jinja2.environment import Environment
+ from mkdocs.config.defaults import MkDocsConfig
+ from mkdocs.structure.files import Files
+
+
+_logger = get_logger("mkdocstrings")
+
+
+class PluginConfig(Config):
+ """The configuration options of `mkdocstrings`, written in `mkdocs.yml`."""
+
+ handlers = opt.Type(dict, default={})
+ """
+ Global configuration of handlers.
+
+ You can set global configuration per handler, applied everywhere,
+ but overridable in each "autodoc" instruction. Example:
+
+ ```yaml
+ plugins:
+ - mkdocstrings:
+ handlers:
+ python:
+ options:
+ option1: true
+ option2: "value"
+ rust:
+ options:
+ option9: 2
+ ```
+ """
+
+ default_handler = opt.Type(str, default="python")
+ """The default handler to use. The value is the name of the handler module. Default is "python"."""
+ custom_templates = opt.Optional(opt.Dir(exists=True))
+ """Location of custom templates to use when rendering API objects.
+
+ Value should be the path of a directory relative to the MkDocs configuration file.
+ """
+ enable_inventory = opt.Optional(opt.Type(bool))
+ """Whether to enable object inventory creation."""
+ enabled = opt.Type(bool, default=True)
+ """Whether to enable the plugin. Default is true. If false, *mkdocstrings* will not collect or render anything."""
+ locale = opt.Optional(opt.Type(str))
+ """The locale to use for translations."""
+
+
+class MkdocstringsPlugin(BasePlugin[PluginConfig]):
+ """An `mkdocs` plugin.
+
+ This plugin defines the following event hooks:
+
+ - `on_config`
+ - `on_env`
+ - `on_post_build`
+
+ Check the [Developing Plugins](https://www.mkdocs.org/user-guide/plugins/#developing-plugins) page of `mkdocs`
+ for more information about its plugin system.
+ """
+
+ css_filename: str = "assets/_mkdocstrings.css"
+ """The path of the CSS file to write in the site directory."""
+
+ def __init__(self) -> None:
+ """Initialize the object."""
+ super().__init__()
+ self._handlers: Handlers | None = None
+
+ @property
+ def handlers(self) -> Handlers:
+ """Get the instance of [mkdocstrings.Handlers][] for this plugin/build.
+
+ Raises:
+ RuntimeError: If the plugin hasn't been initialized with a config.
+
+ Returns:
+ An instance of [mkdocstrings.Handlers][] (the same throughout the build).
+ """
+ if not self._handlers:
+ raise RuntimeError("The plugin hasn't been initialized with a config yet")
+ return self._handlers
+
+ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
+ """Instantiate our Markdown extension.
+
+ Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
+ In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.MkdocstringsExtension]
+ and add it to the list of Markdown extensions used by `mkdocs`.
+
+ 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).
+
+ Arguments:
+ config: The MkDocs config object.
+
+ Returns:
+ The modified config.
+ """
+ if not self.plugin_enabled:
+ _logger.debug("Plugin is not enabled. Skipping.")
+ return config
+ _logger.debug("Adding extension to the list")
+
+ locale = self.config.locale or config.theme.get("language") or config.theme.get("locale") or "en"
+ locale = str(locale).replace("_", "-")
+
+ handlers = Handlers(
+ default=self.config.default_handler,
+ handlers_config=self.config.handlers,
+ theme=config.theme.name or os.path.dirname(config.theme.dirs[0]), # noqa: PTH120
+ custom_templates=self.config.custom_templates,
+ mdx=config.markdown_extensions,
+ mdx_config=config.mdx_configs,
+ inventory_project=config.site_name,
+ inventory_version="0.0.0", # TODO: Find a way to get actual version.
+ locale=locale,
+ tool_config=config,
+ )
+
+ handlers._download_inventories()
+
+ AutorefsPlugin.record_backlinks = True
+ autorefs: AutorefsPlugin
+ try:
+ # If autorefs plugin is explicitly enabled, just use it.
+ autorefs = config.plugins["autorefs"] # ty: ignore[invalid-assignment]
+ _logger.debug("Picked up existing autorefs instance %r", autorefs)
+ except KeyError:
+ # Otherwise, add a limited instance of it that acts only on what's added through `register_anchor`.
+ autorefs = AutorefsPlugin()
+ autorefs.config = AutorefsConfig() # ty:ignore[invalid-assignment]
+ autorefs.scan_toc = False
+ config.plugins["autorefs"] = autorefs
+ _logger.debug("Added a subdued autorefs instance %r", autorefs)
+
+ mkdocstrings_extension = MkdocstringsExtension(handlers, autorefs)
+ config.markdown_extensions.append(mkdocstrings_extension) # ty: ignore[invalid-argument-type]
+
+ config.extra_css.insert(0, self.css_filename) # So that it has lower priority than user files.
+
+ self._autorefs = autorefs
+ self._handlers = handlers
+ return config
+
+ @property
+ def inventory_enabled(self) -> bool:
+ """Tell if the inventory is enabled or not.
+
+ Returns:
+ Whether the inventory is enabled.
+ """
+ inventory_enabled = self.config.enable_inventory
+ if inventory_enabled is None:
+ inventory_enabled = any(handler.enable_inventory for handler in self.handlers.seen_handlers)
+ return inventory_enabled
+
+ @property
+ def plugin_enabled(self) -> bool:
+ """Tell if the plugin is enabled or not.
+
+ Returns:
+ Whether the plugin is enabled.
+ """
+ return self.config.enabled
+
+ @event_priority(50) # Early, before autorefs' starts applying cross-refs and collecting backlinks.
+ def _on_env_load_inventories(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None: # noqa: ARG002
+ if self.plugin_enabled and self._handlers:
+ register = config.plugins["autorefs"].register_url # ty: ignore[unresolved-attribute]
+ for identifier, url in self._handlers._yield_inventory_items():
+ register(identifier, url)
+
+ @event_priority(-20) # Late, not important.
+ def _on_env_add_css(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None: # noqa: ARG002
+ if self.plugin_enabled and self._handlers:
+ css_content = "\n".join(handler.extra_css for handler in self.handlers.seen_handlers)
+ write_file(css_content.encode("utf-8"), os.path.join(config.site_dir, self.css_filename)) # noqa: PTH118
+
+ @event_priority(-20) # Late, not important.
+ def _on_env_write_inventory(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None: # noqa: ARG002
+ if self.plugin_enabled and self._handlers and self.inventory_enabled:
+ _logger.debug("Creating inventory file objects.inv")
+ inv_contents = self.handlers.inventory.format_sphinx()
+ write_file(inv_contents, os.path.join(config.site_dir, "objects.inv")) # noqa: PTH118
+
+ @event_priority(-100) # Last, after autorefs has finished applying cross-refs and collecting backlinks.
+ def _on_env_apply_backlinks(self, env: Environment, /, *, config: MkDocsConfig, files: Files) -> Environment: # noqa: ARG002
+ regex = re.compile(r"")
+
+ def repl(match: Match) -> str:
+ handler_name = match.group(2)
+ handler = self.handlers.get_handler(handler_name)
+
+ # The handler doesn't implement backlinks,
+ # return early to avoid computing them.
+ if handler.render_backlinks.__func__ is BaseHandler.render_backlinks:
+ return ""
+
+ identifier = match.group(1)
+ aliases = handler.get_aliases(identifier)
+ backlinks = self._autorefs.get_backlinks(identifier, *aliases, from_url=file.page.url)
+
+ # No backlinks, avoid calling the handler's method.
+ if not backlinks:
+ return ""
+
+ if "locale" in signature(handler.render_backlinks).parameters:
+ render_backlinks = partial(handler.render_backlinks, locale=self.handlers._locale)
+ else:
+ render_backlinks = handler.render_backlinks
+
+ return render_backlinks(backlinks)
+
+ for file in files:
+ if file.page and file.page.content:
+ _logger.debug("Applying backlinks in page %s", file.page.file.src_path)
+ file.page.content = regex.sub(repl, file.page.content)
+
+ return env
+
+ on_env = CombinedEvent(_on_env_load_inventories, _on_env_add_css, _on_env_write_inventory, _on_env_apply_backlinks)
+ """Extra actions that need to happen after all Markdown-to-HTML page rendering.
+
+ Hook for the [`on_env` event](https://www.mkdocs.org/user-guide/plugins/#on_env).
+
+ - Gather results from background inventory download tasks.
+ - Write mkdocstrings' extra files (CSS, inventory) into the site directory.
+ - Apply backlinks to the HTML output of each page.
+ """
+
+ def on_post_build(
+ self,
+ config: MkDocsConfig, # noqa: ARG002
+ **kwargs: Any, # noqa: ARG002
+ ) -> None:
+ """Teardown the handlers.
+
+ Hook for the [`on_post_build` event](https://www.mkdocs.org/user-guide/plugins/#on_post_build).
+ This hook is used to teardown all the handlers that were instantiated and cached during documentation buildup.
+
+ 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 `teardown` method, which is indirectly called by this hook.
+
+ Arguments:
+ config: The MkDocs config object.
+ **kwargs: Additional arguments passed by MkDocs.
+ """
+ if not self.plugin_enabled:
+ return
+
+ if self._handlers:
+ _logger.debug("Tearing handlers down")
+ self.handlers.teardown()
+
+ def get_handler(self, handler_name: str) -> BaseHandler:
+ """Get a handler by its name. See [mkdocstrings.Handlers.get_handler][].
+
+ Arguments:
+ handler_name: The name of the handler.
+
+ Returns:
+ An instance of a subclass of [`BaseHandler`][mkdocstrings.BaseHandler].
+ """
+ return self.handlers.get_handler(handler_name)
diff --git a/src/mkdocstrings/extension.py b/src/mkdocstrings/extension.py
deleted file mode 100644
index bef8c799..00000000
--- a/src/mkdocstrings/extension.py
+++ /dev/null
@@ -1,306 +0,0 @@
-"""This module holds the code of the Markdown extension responsible for matching "autodoc" instructions.
-
-The extension is composed of a Markdown [block processor](https://python-markdown.github.io/extensions/api/#blockparser)
-that matches indented blocks starting with a line like `::: identifier`.
-
-For each of these blocks, it uses a [handler][mkdocstrings.handlers.base.BaseHandler] to collect documentation about
-the given identifier and render it with Jinja templates.
-
-Both the collection and rendering process can be configured by adding YAML configuration under the "autodoc"
-instruction:
-
-```yaml
-::: some.identifier
- handler: python
- options:
- option1: value1
- option2:
- - value2a
- - value2b
- option_x: etc
-```
-"""
-
-from __future__ import annotations
-
-import re
-from collections import ChainMap
-from typing import TYPE_CHECKING, Any, MutableSequence
-from xml.etree.ElementTree import Element
-
-import yaml
-from jinja2.exceptions import TemplateNotFound
-from markdown.blockprocessors import BlockProcessor
-from markdown.extensions import Extension
-from markdown.treeprocessors import Treeprocessor
-from mkdocs.exceptions import PluginError
-
-from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem, Handlers
-from mkdocstrings.loggers import get_logger
-
-if TYPE_CHECKING:
- from markdown import Markdown
- from markdown.blockparser import BlockParser
- from mkdocs_autorefs.plugin import AutorefsPlugin
-
-
-log = get_logger(__name__)
-
-
-class AutoDocProcessor(BlockProcessor):
- """Our "autodoc" Markdown block processor.
-
- It has a [`test` method][mkdocstrings.extension.AutoDocProcessor.test] that tells if a block matches a criterion,
- and a [`run` method][mkdocstrings.extension.AutoDocProcessor.run] that processes it.
-
- It also has utility methods allowing to get handlers and their configuration easily, useful when processing
- a matched block.
- """
-
- regex = re.compile(r"^(?P#{1,6} *|)::: ?(?P.+?) *$", flags=re.MULTILINE)
-
- def __init__(
- self,
- parser: BlockParser,
- md: Markdown,
- config: dict,
- handlers: Handlers,
- autorefs: AutorefsPlugin,
- ) -> None:
- """Initialize the object.
-
- Arguments:
- parser: A `markdown.blockparser.BlockParser` instance.
- md: A `markdown.Markdown` instance.
- config: The [configuration][mkdocstrings.plugin.PluginConfig] of the `mkdocstrings` plugin.
- handlers: The handlers container.
- autorefs: The autorefs plugin instance.
- """
- super().__init__(parser=parser)
- self.md = md
- self._config = config
- self._handlers = handlers
- self._autorefs = autorefs
- self._updated_envs: set = set()
-
- def test(self, parent: Element, block: str) -> bool: # noqa: ARG002
- """Match our autodoc instructions.
-
- Arguments:
- parent: The parent element in the XML tree.
- block: The block to be tested.
-
- Returns:
- Whether this block should be processed or not.
- """
- return bool(self.regex.search(block))
-
- def run(self, parent: Element, blocks: MutableSequence[str]) -> None:
- """Run code on the matched blocks.
-
- The identifier and configuration lines are retrieved from a matched block
- and used to collect and render an object.
-
- Arguments:
- parent: The parent element in the XML tree.
- blocks: The rest of the blocks to be processed.
- """
- block = blocks.pop(0)
- match = self.regex.search(block)
-
- if match:
- if match.start() > 0:
- self.parser.parseBlocks(parent, [block[: match.start()]])
- # removes the first line
- block = block[match.end() :]
-
- block, the_rest = self.detab(block)
-
- if match:
- identifier = match["name"]
- heading_level = match["heading"].count("#")
- log.debug(f"Matched '::: {identifier}'")
-
- html, handler, data = self._process_block(identifier, block, heading_level)
- el = Element("div", {"class": "mkdocstrings"})
- # The final HTML is inserted as opaque to subsequent processing, and only revealed at the end.
- el.text = self.md.htmlStash.store(html)
- # So we need to duplicate the headings directly (and delete later), just so 'toc' can pick them up.
- headings = handler.get_headings()
- el.extend(headings)
-
- page = self._autorefs.current_page
- if page is not None:
- for heading in headings:
- rendered_anchor = heading.attrib["id"]
- self._autorefs.register_anchor(page, rendered_anchor)
-
- if "data-role" in heading.attrib:
- self._handlers.inventory.register(
- name=rendered_anchor,
- domain=handler.domain,
- role=heading.attrib["data-role"],
- priority=1, # register with standard priority
- uri=f"{page}#{rendered_anchor}",
- )
-
- # also register other anchors for this object in the inventory
- try:
- data_object = handler.collect(rendered_anchor, handler.fallback_config)
- except CollectionError:
- continue
- for anchor in handler.get_anchors(data_object):
- if anchor not in self._handlers.inventory:
- self._handlers.inventory.register(
- name=anchor,
- domain=handler.domain,
- role=heading.attrib["data-role"],
- priority=2, # register with lower priority
- uri=f"{page}#{rendered_anchor}",
- )
-
- parent.append(el)
-
- if the_rest:
- # This block contained unindented line(s) after the first indented
- # line. Insert these lines as the first block of the master blocks
- # list for future processing.
- blocks.insert(0, the_rest)
-
- def _process_block(
- self,
- identifier: str,
- yaml_block: str,
- heading_level: int = 0,
- ) -> tuple[str, BaseHandler, CollectorItem]:
- """Process an autodoc block.
-
- Arguments:
- identifier: The identifier of the object to collect and render.
- yaml_block: The YAML configuration.
- heading_level: Suggested level of the heading to insert (0 to ignore).
-
- Raises:
- PluginError: When something wrong happened during collection.
- TemplateNotFound: When a template used for rendering could not be found.
-
- Returns:
- Rendered HTML, the handler that was used, and the collected item.
- """
- config = yaml.safe_load(yaml_block) or {}
- handler_name = self._handlers.get_handler_name(config)
-
- log.debug(f"Using handler '{handler_name}'")
- handler_config = self._handlers.get_handler_config(handler_name)
- handler = self._handlers.get_handler(handler_name, handler_config)
-
- global_options = handler_config.get("options", {})
- local_options = config.get("options", {})
- options = ChainMap(local_options, global_options)
-
- if heading_level:
- options = ChainMap(options, {"heading_level": heading_level}) # like setdefault
-
- log.debug("Collecting data")
- try:
- data: CollectorItem = handler.collect(identifier, options)
- except CollectionError as exception:
- log.error(str(exception)) # noqa: TRY400
- if PluginError is SystemExit: # TODO: when MkDocs 1.2 is sufficiently common, this can be dropped.
- log.error(f"Error reading page '{self._autorefs.current_page}':") # noqa: TRY400
- raise PluginError(f"Could not collect '{identifier}'") from exception
-
- if handler_name not in self._updated_envs: # We haven't seen this handler before on this document.
- log.debug("Updating handler's rendering env")
- handler._update_env(self.md, self._config)
- self._updated_envs.add(handler_name)
-
- log.debug("Rendering templates")
- try:
- rendered = handler.render(data, options)
- except TemplateNotFound as exc:
- theme_name = self._config["theme_name"]
- log.error( # noqa: TRY400
- f"Template '{exc.name}' not found for '{handler_name}' handler and theme '{theme_name}'.",
- )
- raise
-
- return rendered, handler, data
-
-
-class _HeadingsPostProcessor(Treeprocessor):
- def run(self, root: Element) -> None:
- self._remove_duplicated_headings(root)
-
- def _remove_duplicated_headings(self, parent: Element) -> None:
- carry_text = ""
- for el in reversed(parent): # Reversed mainly for the ability to mutate during iteration.
- if el.tag == "div" and el.get("class") == "mkdocstrings":
- # Delete the duplicated headings along with their container, but keep the text (i.e. the actual HTML).
- carry_text = (el.text or "") + carry_text
- parent.remove(el)
- else:
- if carry_text:
- el.tail = (el.tail or "") + carry_text
- carry_text = ""
- self._remove_duplicated_headings(el)
-
- if carry_text:
- parent.text = (parent.text or "") + carry_text
-
-
-class _TocLabelsTreeProcessor(Treeprocessor):
- def run(self, root: Element) -> None: # noqa: ARG002
- self._override_toc_labels(self.md.toc_tokens) # type: ignore[attr-defined]
-
- def _override_toc_labels(self, tokens: list[dict[str, Any]]) -> None:
- for token in tokens:
- if (label := token.get("data-toc-label")) and token["name"] != label:
- token["name"] = label
- self._override_toc_labels(token["children"])
-
-
-class MkdocstringsExtension(Extension):
- """Our Markdown extension.
-
- It cannot work outside of `mkdocstrings`.
- """
-
- def __init__(self, config: dict, handlers: Handlers, autorefs: AutorefsPlugin, **kwargs: Any) -> None:
- """Initialize the object.
-
- Arguments:
- config: The configuration items from `mkdocs` and `mkdocstrings` that must be passed to the block processor
- when instantiated in [`extendMarkdown`][mkdocstrings.extension.MkdocstringsExtension.extendMarkdown].
- handlers: The handlers container.
- autorefs: The autorefs plugin instance.
- **kwargs: Keyword arguments used by `markdown.extensions.Extension`.
- """
- super().__init__(**kwargs)
- self._config = config
- self._handlers = handlers
- self._autorefs = autorefs
-
- def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name)
- """Register the extension.
-
- Add an instance of our [`AutoDocProcessor`][mkdocstrings.extension.AutoDocProcessor] to the Markdown parser.
-
- Arguments:
- md: A `markdown.Markdown` instance.
- """
- md.parser.blockprocessors.register(
- AutoDocProcessor(md.parser, md, self._config, self._handlers, self._autorefs),
- "mkdocstrings",
- priority=75, # Right before markdown.blockprocessors.HashHeaderProcessor
- )
- md.treeprocessors.register(
- _HeadingsPostProcessor(md),
- "mkdocstrings_post_headings",
- priority=4, # Right after 'toc'.
- )
- md.treeprocessors.register(
- _TocLabelsTreeProcessor(md),
- "mkdocstrings_post_toc_labels",
- priority=4, # Right after 'toc'.
- )
diff --git a/src/mkdocstrings/handlers/__init__.py b/src/mkdocstrings/handlers/__init__.py
deleted file mode 100644
index b9e2a29c..00000000
--- a/src/mkdocstrings/handlers/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-"""Handlers module."""
diff --git a/src/mkdocstrings/handlers/base.py b/src/mkdocstrings/handlers/base.py
deleted file mode 100644
index f52e17dc..00000000
--- a/src/mkdocstrings/handlers/base.py
+++ /dev/null
@@ -1,482 +0,0 @@
-"""Base module for handlers.
-
-This module contains the base classes for implementing handlers.
-"""
-
-from __future__ import annotations
-
-import importlib
-import sys
-from pathlib import Path
-from typing import Any, BinaryIO, ClassVar, Iterable, Iterator, Mapping, MutableMapping, Sequence, cast
-from xml.etree.ElementTree import Element, tostring
-
-from jinja2 import Environment, FileSystemLoader
-from markdown import Markdown
-from markdown.extensions.toc import TocTreeprocessor
-from markupsafe import Markup
-
-from mkdocstrings.handlers.rendering import (
- HeadingShiftingTreeprocessor,
- Highlighter,
- IdPrependingTreeprocessor,
- MkdocstringsInnerExtension,
- ParagraphStrippingTreeprocessor,
-)
-from mkdocstrings.inventory import Inventory
-from mkdocstrings.loggers import get_template_logger
-
-# TODO: remove once support for Python 3.9 is dropped
-if sys.version_info < (3, 10):
- from importlib_metadata import entry_points
-else:
- from importlib.metadata import entry_points
-
-CollectorItem = Any
-
-
-class CollectionError(Exception):
- """An exception raised when some collection of data failed."""
-
-
-class ThemeNotSupported(Exception): # noqa: N818
- """An exception raised to tell a theme is not supported."""
-
-
-def do_any(seq: Sequence, attribute: str | None = None) -> bool:
- """Check if at least one of the item in the sequence evaluates to true.
-
- The `any` builtin as a filter for Jinja templates.
-
- Arguments:
- seq: An iterable object.
- attribute: The attribute name to use on each object of the iterable.
-
- Returns:
- A boolean telling if any object of the iterable evaluated to True.
- """
- if attribute is None:
- return any(seq)
- return any(_[attribute] for _ in seq)
-
-
-class BaseHandler:
- """The base handler class.
-
- Inherit from this class to implement a handler.
-
- You will have to implement the `collect` and `render` methods.
- You can also implement the `teardown` method,
- and override the `update_env` method, to add more filters to the Jinja environment,
- making them available in your Jinja templates.
-
- To define a fallback theme, add a `fallback_theme` class-variable.
- To add custom CSS, add an `extra_css` variable or create an 'style.css' file beside the templates.
- """
-
- name: str = ""
- """The handler's name, for example "python"."""
- domain: str = "default"
- """The handler's domain, used to register objects in the inventory, for example "py"."""
- enable_inventory: bool = False
- """Whether the inventory creation is enabled."""
- fallback_config: ClassVar[dict] = {}
- """Fallback configuration when searching anchors for identifiers."""
- fallback_theme: str = ""
- """Fallback theme to use when a template isn't found in the configured theme."""
- extra_css = ""
- """Extra CSS."""
-
- def __init__(self, handler: str, theme: str, custom_templates: str | None = None) -> None:
- """Initialize the object.
-
- If the given theme is not supported (it does not exist), it will look for a `fallback_theme` attribute
- in `self` to use as a fallback theme.
-
- Arguments:
- handler: The name of the handler.
- theme: The name of theme to use.
- custom_templates: Directory containing custom templates.
- """
- paths = []
-
- # add selected theme templates
- themes_dir = self.get_templates_dir(handler)
- paths.append(themes_dir / theme)
-
- # add extended theme templates
- extended_templates_dirs = self.get_extended_templates_dirs(handler)
- for templates_dir in extended_templates_dirs:
- paths.append(templates_dir / theme)
-
- # add fallback theme templates
- if self.fallback_theme and self.fallback_theme != theme:
- paths.append(themes_dir / self.fallback_theme)
-
- # add fallback theme of extended templates
- for templates_dir in extended_templates_dirs:
- paths.append(templates_dir / self.fallback_theme)
-
- for path in paths:
- css_path = path / "style.css"
- if css_path.is_file():
- self.extra_css += "\n" + css_path.read_text(encoding="utf-8")
- break
-
- if custom_templates is not None:
- paths.insert(0, Path(custom_templates) / handler / theme)
-
- self.env = Environment(
- autoescape=True,
- loader=FileSystemLoader(paths),
- auto_reload=False, # Editing a template in the middle of a build is not useful.
- )
- self.env.filters["any"] = do_any
- self.env.globals["log"] = get_template_logger()
-
- self._headings: list[Element] = []
- self._md: Markdown = None # type: ignore[assignment] # To be populated in `update_env`.
-
- @classmethod
- def load_inventory(
- cls,
- in_file: BinaryIO, # noqa: ARG003
- url: str, # noqa: ARG003
- base_url: str | None = None, # noqa: ARG003
- **kwargs: Any, # noqa: ARG003
- ) -> Iterator[tuple[str, str]]:
- """Yield items and their URLs from an inventory file streamed from `in_file`.
-
- Arguments:
- in_file: The binary file-like object to read the inventory from.
- url: The URL that this file is being streamed from (used to guess `base_url`).
- base_url: The URL that this inventory's sub-paths are relative to.
- **kwargs: Ignore additional arguments passed from the config.
-
- Yields:
- Tuples of (item identifier, item URL).
- """
- yield from ()
-
- def collect(self, identifier: str, config: MutableMapping[str, Any]) -> CollectorItem:
- """Collect data given an identifier and user configuration.
-
- 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.
-
- Arguments:
- identifier: An identifier for which to collect data. For example, in Python,
- it would be 'mkdocstrings.handlers' to collect documentation about the handlers module.
- It can be anything that you can feed to the tool of your choice.
- config: The handler's configuration options.
-
- Returns:
- Anything you want, as long as you can feed it to the handler's `render` method.
- """
- raise NotImplementedError
-
- def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:
- """Render a template using provided data and configuration options.
-
- Arguments:
- data: The collected data to render.
- config: The handler's configuration options.
-
- Returns:
- The rendered template as HTML.
- """
- raise NotImplementedError
-
- def teardown(self) -> None:
- """Teardown the handler.
-
- This method should be implemented to, for example, terminate a subprocess
- that was started when creating the handler instance.
- """
-
- def get_templates_dir(self, handler: str | None = None) -> Path:
- """Return the path to the handler's templates directory.
-
- Override to customize how the templates directory is found.
-
- Arguments:
- handler: The name of the handler to get the templates directory of.
-
- Raises:
- ModuleNotFoundError: When no such handler is installed.
- FileNotFoundError: When the templates directory cannot be found.
-
- Returns:
- The templates directory path.
- """
- handler = handler or self.name
- try:
- import mkdocstrings_handlers
- except ModuleNotFoundError as error:
- raise ModuleNotFoundError(f"Handler '{handler}' not found, is it installed?") from error
-
- for path in mkdocstrings_handlers.__path__:
- theme_path = Path(path, handler, "templates")
- if theme_path.exists():
- return theme_path
-
- raise FileNotFoundError(f"Can't find 'templates' folder for handler '{handler}'")
-
- def get_extended_templates_dirs(self, handler: str) -> list[Path]:
- """Load template extensions for the given handler, return their templates directories.
-
- Arguments:
- handler: The name of the handler to get the extended templates directory of.
-
- Returns:
- The extensions templates directories.
- """
- discovered_extensions = entry_points(group=f"mkdocstrings.{handler}.templates")
- return [extension.load()() for extension in discovered_extensions]
-
- def get_anchors(self, data: CollectorItem) -> tuple[str, ...]:
- """Return the possible identifiers (HTML anchors) for a collected item.
-
- Arguments:
- data: The collected data.
-
- Returns:
- The HTML anchors (without '#'), or an empty tuple if this item doesn't have an anchor.
- """
- # TODO: remove this when https://github.com/mkdocstrings/crystal/pull/6 is merged and released
- try:
- return (self.get_anchor(data),) # type: ignore[attr-defined]
- except AttributeError:
- return ()
-
- def do_convert_markdown(
- self,
- text: str,
- heading_level: int,
- html_id: str = "",
- *,
- strip_paragraph: bool = False,
- ) -> Markup:
- """Render Markdown text; for use inside templates.
-
- Arguments:
- text: The text to convert.
- heading_level: The base heading level to start all Markdown headings from.
- html_id: The HTML id of the element that's considered the parent of this element.
- strip_paragraph: Whether to exclude the tag from around the whole output.
-
- Returns:
- An HTML string.
- """
- treeprocessors = self._md.treeprocessors
- treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level # type: ignore[attr-defined]
- treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--" # type: ignore[attr-defined]
- treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph # type: ignore[attr-defined]
- try:
- return Markup(self._md.convert(text))
- finally:
- treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0 # type: ignore[attr-defined]
- treeprocessors[IdPrependingTreeprocessor.name].id_prefix = "" # type: ignore[attr-defined]
- treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False # type: ignore[attr-defined]
- self._md.reset()
-
- def do_heading(
- self,
- content: Markup,
- heading_level: int,
- *,
- role: str | None = None,
- hidden: bool = False,
- toc_label: str | None = None,
- **attributes: str,
- ) -> Markup:
- """Render an HTML heading and register it for the table of contents. For use inside templates.
-
- Arguments:
- content: The HTML within the heading.
- heading_level: The level of heading (e.g. 3 -> `h3`).
- role: An optional role for the object bound to this heading.
- hidden: If True, only register it for the table of contents, don't render anything.
- toc_label: The title to use in the table of contents ('data-toc-label' attribute).
- **attributes: Any extra HTML attributes of the heading.
-
- Returns:
- An HTML string.
- """
- # First, produce the "fake" heading, for ToC only.
- el = Element(f"h{heading_level}", attributes)
- if toc_label is None:
- toc_label = content.unescape() if isinstance(content, Markup) else content
- el.set("data-toc-label", toc_label)
- if role:
- el.set("data-role", role)
- self._headings.append(el)
-
- if hidden:
- return Markup('').format(attributes["id"])
-
- # Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.
- # Start with a heading that has just attributes (no text), and add a placeholder into it.
- el = Element(f"h{heading_level}", attributes)
- el.append(Element("mkdocstrings-placeholder"))
- # Tell the 'toc' extension to make its additions if configured so.
- toc = cast(TocTreeprocessor, self._md.treeprocessors["toc"])
- if toc.use_anchors:
- toc.add_anchor(el, attributes["id"])
- if toc.use_permalinks:
- toc.add_permalink(el, attributes["id"])
-
- # The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle
- # of the heading with a placeholder that can never occur (text can't directly contain angle brackets).
- # Now this HTML wrapper can be "filled" by replacing the placeholder.
- html_with_placeholder = tostring(el, encoding="unicode")
- assert ( # noqa: S101
- html_with_placeholder.count("
` tag from around the whole output.
+
+ Returns:
+ An HTML string.
+ """
+ global _markdown_conversion_layer # noqa: PLW0603
+ _markdown_conversion_layer += 1
+ treeprocessors = self.md.treeprocessors
+ treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level
+ treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--"
+ treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph
+ if BacklinksTreeProcessor.name in treeprocessors:
+ treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id
+ if autoref_hook and AutorefsInlineProcessor.name in self.md.inlinePatterns:
+ self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook # ty: ignore[unresolved-attribute]
+
+ try:
+ return Markup(self.md.convert(text))
+ finally:
+ treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0
+ treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""
+ treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False
+ if BacklinksTreeProcessor.name in treeprocessors:
+ treeprocessors[BacklinksTreeProcessor.name].initial_id = None
+ if AutorefsInlineProcessor.name in self.md.inlinePatterns:
+ self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = None
+ self.md.reset()
+ _markdown_conversion_layer -= 1
+
+ def do_heading(
+ self,
+ content: Markup,
+ heading_level: int,
+ *,
+ role: str | None = None,
+ hidden: bool = False,
+ toc_label: str | None = None,
+ skip_inventory: bool = False,
+ **attributes: str,
+ ) -> Markup:
+ """Render an HTML heading and register it for the table of contents. For use inside templates.
+
+ Arguments:
+ content: The HTML within the heading.
+ heading_level: The level of heading (e.g. 3 -> `h3`).
+ role: An optional role for the object bound to this heading.
+ hidden: If True, only register it for the table of contents, don't render anything.
+ toc_label: The title to use in the table of contents ('data-toc-label' attribute).
+ skip_inventory: Flag element to not be registered in the inventory (by setting a `data-skip-inventory` attribute).
+ **attributes: Any extra HTML attributes of the heading.
+
+ Returns:
+ An HTML string.
+ """
+ # Produce a heading element that will be used later, in `AutoDocProcessor.run`, to:
+ # - register it in the ToC: right now we're in the inner Markdown conversion layer,
+ # so we have to bubble up the information to the outer Markdown conversion layer,
+ # for the ToC extension to pick it up.
+ # - register it in autorefs: right now we don't know what page is being rendered,
+ # so we bubble up the information again to where autorefs knows the page,
+ # and can correctly register the heading anchor (id) to its full URL.
+ # - register it in the objects inventory: same as for autorefs,
+ # we don't know the page here, or the handler (and its domain),
+ # so we bubble up the information to where the mkdocstrings extension knows that.
+ el = Element(f"h{heading_level}", attributes)
+ if toc_label is None:
+ toc_label = content.unescape() if isinstance(content, Markup) else content
+ el.set("data-toc-label", toc_label)
+ if skip_inventory:
+ el.set("data-skip-inventory", "true")
+ if role:
+ el.set("data-role", role)
+ if content:
+ el.text = str(content).strip()
+ self._headings.append(el)
+
+ if hidden:
+ return Markup('').format(attributes["id"])
+
+ # Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.
+ # Start with a heading that has just attributes (no text), and add a placeholder into it.
+ el = Element(f"h{heading_level}", attributes)
+ el.append(Element("mkdocstrings-placeholder"))
+ # Tell the inner 'toc' extension to make its additions if configured so.
+ toc = cast("TocTreeprocessor", self.md.treeprocessors["toc"])
+ if toc.use_anchors:
+ toc.add_anchor(el, attributes["id"])
+ if toc.use_permalinks:
+ toc.add_permalink(el, attributes["id"])
+
+ # The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle
+ # of the heading with a placeholder that can never occur (text can't directly contain angle brackets).
+ # Now this HTML wrapper can be "filled" by replacing the placeholder.
+ html_with_placeholder = tostring(el, encoding="unicode")
+ assert ( # noqa: S101
+ html_with_placeholder.count("
` with `shift_by = 3` becomes ``."""
@@ -205,7 +210,8 @@ def __init__(self, md: Markdown, shift_by: int):
super().__init__(md)
self.shift_by = shift_by
- def run(self, root: Element) -> None: # noqa: D102 (ignore missing docstring)
+ def run(self, root: Element) -> None:
+ """Shift the levels of all headings in the document."""
if not self.shift_by:
return
for el in root.iter():
@@ -219,8 +225,11 @@ def run(self, root: Element) -> None: # noqa: D102 (ignore missing docstring)
class _HeadingReportingTreeprocessor(Treeprocessor):
"""Records the heading elements encountered in the document."""
- name = "mkdocstrings_headings_list"
- regex = re.compile(r"[Hh][1-6]")
+ name: str = "mkdocstrings_headings_list"
+ """The name of the treeprocessor."""
+
+ regex: re.Pattern = re.compile(r"[Hh][1-6]")
+ """The regex to match heading tags."""
headings: list[Element]
"""The list (the one passed in the initializer) that is used to record the heading elements (by appending to it)."""
@@ -230,7 +239,8 @@ def __init__(self, md: Markdown, headings: list[Element]):
self.headings = headings
def run(self, root: Element) -> None:
- permalink_class = self.md.treeprocessors["toc"].permalink_class # type: ignore[attr-defined]
+ """Record all heading elements encountered in the document."""
+ permalink_class = self.md.treeprocessors["toc"].permalink_class
for el in root.iter():
if self.regex.fullmatch(el.tag):
el = copy.copy(el) # noqa: PLW2901
@@ -242,14 +252,18 @@ def run(self, root: Element) -> None:
class ParagraphStrippingTreeprocessor(Treeprocessor):
- """Unwraps the
element around the whole output.""" + """Unwraps the `
` element around the whole output.""" + + name: str = "mkdocstrings_strip_paragraph" + """The name of the treeprocessor.""" - name = "mkdocstrings_strip_paragraph" - strip = False + strip: bool = False + """Whether to strip `
` elements or not.""" - def run(self, root: Element) -> Element | None: # noqa: D102 (ignore missing docstring) + def run(self, root: Element) -> Element | None: + """Unwrap the root element if it's a single `
` element.""" if self.strip and len(root) == 1 and root[0].tag == "p": - # Turn the single
element into the root element and inherit its tag name (it's significant!) + # Turn the single `
` element into the root element and inherit its tag name (it's significant!)
root[0].tag = root.tag
return root[0]
return None
@@ -266,6 +280,7 @@ def __init__(self, headings: list[Element]):
"""
super().__init__()
self.headings = headings
+ """The list that will be populated with all HTML heading elements encountered in the document."""
def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name)
"""Register the extension.
diff --git a/src/mkdocstrings/inventory.py b/src/mkdocstrings/_internal/inventory.py
similarity index 81%
rename from src/mkdocstrings/inventory.py
rename to src/mkdocstrings/_internal/inventory.py
index f1c8962a..241bbb12 100644
--- a/src/mkdocstrings/inventory.py
+++ b/src/mkdocstrings/_internal/inventory.py
@@ -1,14 +1,17 @@
-"""Module responsible for the objects inventory."""
-
+# Module responsible for the objects inventory.
+#
# Credits to Brian Skinn and the sphobjinv project:
-# https://github.com/bskinn/sphobjinv
+# https://github.com/bskinn/sphobjinv.
from __future__ import annotations
import re
import zlib
from textwrap import dedent
-from typing import BinaryIO, Collection
+from typing import TYPE_CHECKING, BinaryIO, Literal, overload
+
+if TYPE_CHECKING:
+ from collections.abc import Collection
class InventoryItem:
@@ -34,11 +37,17 @@ def __init__(
dispname: The item display name.
"""
self.name: str = name
+ """The item name."""
self.domain: str = domain
+ """The item domain."""
self.role: str = role
+ """The item role."""
self.uri: str = uri
+ """The item URI."""
self.priority: int = priority
+ """The item priority."""
self.dispname: str = dispname or name
+ """The item display name."""
def format_sphinx(self) -> str:
"""Format this item as a Sphinx inventory line.
@@ -55,12 +64,23 @@ def format_sphinx(self) -> str:
return f"{self.name} {self.domain}:{self.role} {self.priority} {uri} {dispname}"
sphinx_item_regex = re.compile(r"^(.+?)\s+(\S+):(\S+)\s+(-?\d+)\s+(\S+)\s*(.*)$")
+ """Regex to parse a Sphinx v2 inventory line."""
+
+ @overload
+ @classmethod
+ def parse_sphinx(cls, line: str, *, return_none: Literal[False]) -> InventoryItem: ...
+ @overload
@classmethod
- def parse_sphinx(cls, line: str) -> InventoryItem:
+ def parse_sphinx(cls, line: str, *, return_none: Literal[True]) -> InventoryItem | None: ...
+
+ @classmethod
+ def parse_sphinx(cls, line: str, *, return_none: bool = False) -> InventoryItem | None:
"""Parse a line from a Sphinx v2 inventory file and return an `InventoryItem` from it."""
match = cls.sphinx_item_regex.search(line)
if not match:
+ if return_none:
+ return None
raise ValueError(line)
name, domain, role, priority, uri, dispname = match.groups()
if uri.endswith("$"):
@@ -86,7 +106,9 @@ def __init__(self, items: list[InventoryItem] | None = None, project: str = "pro
for item in items:
self[item.name] = item
self.project = project
+ """The project name."""
self.version = version
+ """The project version."""
def register(
self,
@@ -155,7 +177,9 @@ def parse_sphinx(cls, in_file: BinaryIO, *, domain_filter: Collection[str] = ())
for _ in range(4):
in_file.readline()
lines = zlib.decompress(in_file.read()).splitlines()
- items = [InventoryItem.parse_sphinx(line.decode("utf8")) for line in lines]
+ items: list[InventoryItem] = [
+ item for line in lines if (item := InventoryItem.parse_sphinx(line.decode("utf8"), return_none=True))
+ ]
if domain_filter:
items = [item for item in items if item.domain in domain_filter]
return cls(items)
diff --git a/src/mkdocstrings/loggers.py b/src/mkdocstrings/_internal/loggers.py
similarity index 53%
rename from src/mkdocstrings/loggers.py
rename to src/mkdocstrings/_internal/loggers.py
index 63502474..6c8817ac 100644
--- a/src/mkdocstrings/loggers.py
+++ b/src/mkdocstrings/_internal/loggers.py
@@ -1,31 +1,49 @@
-"""Logging functions."""
+# Logging functions.
from __future__ import annotations
import logging
from contextlib import suppress
from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, MutableMapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from jinja2 import pass_context
+
+if TYPE_CHECKING:
+ from collections.abc import Callable, MutableMapping, Sequence
+
+ from jinja2.runtime import Context
-try:
- from jinja2 import pass_context
-except ImportError: # TODO: remove once Jinja2 < 3.1 is dropped
- from jinja2 import contextfunction as pass_context # type: ignore[attr-defined,no-redef]
try:
import mkdocstrings_handlers
except ImportError:
TEMPLATES_DIRS: Sequence[Path] = ()
else:
- TEMPLATES_DIRS = tuple(mkdocstrings_handlers.__path__) # type: ignore[arg-type]
+ TEMPLATES_DIRS = tuple(mkdocstrings_handlers.__path__)
+ """The directories where the handler templates are located."""
-if TYPE_CHECKING:
- from jinja2.runtime import Context
+class LoggerAdapter(logging.LoggerAdapter):
+ """A logger adapter to prefix messages.
+ This adapter also adds an additional parameter to logging methods
+ called `once`: if `True`, the message will only be logged once.
-class LoggerAdapter(logging.LoggerAdapter):
- """A logger adapter to prefix messages."""
+ Examples:
+ In Python code:
+
+ >>> logger = get_logger("myplugin")
+ >>> logger.debug("This is a debug message.")
+ >>> logger.info("This is an info message.", once=True)
+
+ In Jinja templates (logger available in context as `log`):
+
+ ```jinja
+ {{ log.debug("This is a debug message.") }}
+ {{ log.info("This is an info message.", once=True) }}
+ ```
+ """
def __init__(self, prefix: str, logger: logging.Logger):
"""Initialize the object.
@@ -36,6 +54,8 @@ def __init__(self, prefix: str, logger: logging.Logger):
"""
super().__init__(logger, {})
self.prefix = prefix
+ """The prefix to insert in front of every message."""
+ self._logged: set[tuple[LoggerAdapter, str]] = set()
def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, Any]:
"""Process the message.
@@ -49,11 +69,32 @@ def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, Any]
"""
return f"{self.prefix}: {msg}", kwargs
+ def log(self, level: int, msg: object, *args: object, **kwargs: object) -> None:
+ """Log a message.
+
+ Arguments:
+ level: The logging level.
+ msg: The message.
+ *args: Additional arguments passed to parent method.
+ **kwargs: Additional keyword arguments passed to parent method.
+ """
+ if kwargs.pop("once", False):
+ if (key := (self, str(msg))) in self._logged:
+ return
+ self._logged.add(key)
+ super().log(level, msg, *args, **kwargs) # ty: ignore[invalid-argument-type]
+
class TemplateLogger:
"""A wrapper class to allow logging in templates.
- Attributes:
+ The logging methods provided by this class all accept
+ two parameters:
+
+ - `msg`: The message to log.
+ - `once`: If `True`, the message will only be logged once.
+
+ Methods:
debug: Function to log a DEBUG message.
info: Function to log an INFO message.
warning: Function to log a WARNING message.
@@ -68,10 +109,36 @@ def __init__(self, logger: LoggerAdapter):
logger: A logger adapter.
"""
self.debug = get_template_logger_function(logger.debug)
+ """Log a DEBUG message."""
self.info = get_template_logger_function(logger.info)
+ """Log an INFO message."""
self.warning = get_template_logger_function(logger.warning)
+ """Log a WARNING message."""
self.error = get_template_logger_function(logger.error)
+ """Log an ERROR message."""
self.critical = get_template_logger_function(logger.critical)
+ """Log a CRITICAL message."""
+
+
+class _Lazy:
+ unset = object()
+
+ def __init__(self, func: Callable, *args: Any, **kwargs: Any):
+ self.func = func
+ self.args = args
+ self.kwargs = kwargs
+ self.result = self.unset
+
+ def __call__(self):
+ if self.result is self.unset:
+ self.result = self.func(*self.args, **self.kwargs)
+ return self.result
+
+ def __str__(self) -> str:
+ return str(self())
+
+ def __repr__(self) -> str:
+ return repr(self())
def get_template_logger_function(logger_func: Callable) -> Callable:
@@ -85,18 +152,18 @@ def get_template_logger_function(logger_func: Callable) -> Callable:
"""
@pass_context
- def wrapper(context: Context, msg: str | None = None) -> str:
+ def wrapper(context: Context, msg: str | None = None, *args: Any, **kwargs: Any) -> str:
"""Log a message.
Arguments:
context: The template context, automatically provided by Jinja.
msg: The message to log.
+ **kwargs: Additional arguments passed to the logger function.
Returns:
An empty string.
"""
- template_path = get_template_path(context)
- logger_func(f"{template_path}: {msg or 'Rendering'}")
+ logger_func(f"%s: {msg or 'Rendering'}", _Lazy(get_template_path, context), *args, **kwargs)
return ""
return wrapper
@@ -136,10 +203,14 @@ def get_logger(name: str) -> LoggerAdapter:
return LoggerAdapter(name.split(".", 1)[0], logger)
-def get_template_logger() -> TemplateLogger:
+def get_template_logger(handler_name: str | None = None) -> TemplateLogger:
"""Return a logger usable in templates.
+ Parameters:
+ handler_name: The name of the handler.
+
Returns:
A template logger.
"""
- return TemplateLogger(get_logger("mkdocstrings.templates"))
+ handler_name = handler_name or "base"
+ return TemplateLogger(get_logger(f"mkdocstrings_handlers.{handler_name}.templates"))
diff --git a/src/mkdocstrings/_internal/plugin.py b/src/mkdocstrings/_internal/plugin.py
new file mode 100644
index 00000000..4f9bd29d
--- /dev/null
+++ b/src/mkdocstrings/_internal/plugin.py
@@ -0,0 +1,298 @@
+# This module contains the "mkdocstrings" plugin for MkDocs.
+#
+# The plugin instantiates a Markdown extension ([`MkdocstringsExtension`][mkdocstrings.MkdocstringsExtension]),
+# and adds it to the list of Markdown extensions used by `mkdocs`
+# during the [`on_config` event hook](https://www.mkdocs.org/user-guide/plugins/#on_config).
+#
+# Once the documentation is built, the [`on_post_build` event hook](https://www.mkdocs.org/user-guide/plugins/#on_post_build)
+# is triggered and calls the [`handlers.teardown()` method][mkdocstrings.Handlers.teardown]. This method is
+# used to teardown the handlers that were instantiated during documentation buildup.
+#
+# Finally, when serving the documentation, it can add directories to watch
+# during the [`on_serve` event hook](https://www.mkdocs.org/user-guide/plugins/#on_serve).
+
+from __future__ import annotations
+
+import os
+import re
+from functools import partial
+from inspect import signature
+from re import Match
+from typing import TYPE_CHECKING, Any
+
+from mkdocs.config import Config
+from mkdocs.config import config_options as opt
+from mkdocs.plugins import BasePlugin, CombinedEvent, event_priority
+from mkdocs.utils import write_file
+from mkdocs_autorefs import AutorefsConfig, AutorefsPlugin
+
+from mkdocstrings._internal.extension import MkdocstringsExtension
+from mkdocstrings._internal.handlers.base import BaseHandler, Handlers
+from mkdocstrings._internal.loggers import get_logger
+
+if TYPE_CHECKING:
+ from jinja2.environment import Environment
+ from mkdocs.config.defaults import MkDocsConfig
+ from mkdocs.structure.files import Files
+
+
+_logger = get_logger("mkdocstrings")
+
+
+class PluginConfig(Config):
+ """The configuration options of `mkdocstrings`, written in `mkdocs.yml`."""
+
+ handlers = opt.Type(dict, default={})
+ """
+ Global configuration of handlers.
+
+ You can set global configuration per handler, applied everywhere,
+ but overridable in each "autodoc" instruction. Example:
+
+ ```yaml
+ plugins:
+ - mkdocstrings:
+ handlers:
+ python:
+ options:
+ option1: true
+ option2: "value"
+ rust:
+ options:
+ option9: 2
+ ```
+ """
+
+ default_handler = opt.Type(str, default="python")
+ """The default handler to use. The value is the name of the handler module. Default is "python"."""
+ custom_templates = opt.Optional(opt.Dir(exists=True))
+ """Location of custom templates to use when rendering API objects.
+
+ Value should be the path of a directory relative to the MkDocs configuration file.
+ """
+ enable_inventory = opt.Optional(opt.Type(bool))
+ """Whether to enable object inventory creation."""
+ enabled = opt.Type(bool, default=True)
+ """Whether to enable the plugin. Default is true. If false, *mkdocstrings* will not collect or render anything."""
+ locale = opt.Optional(opt.Type(str))
+ """The locale to use for translations."""
+
+
+class MkdocstringsPlugin(BasePlugin[PluginConfig]):
+ """An `mkdocs` plugin.
+
+ This plugin defines the following event hooks:
+
+ - `on_config`
+ - `on_env`
+ - `on_post_build`
+
+ Check the [Developing Plugins](https://www.mkdocs.org/user-guide/plugins/#developing-plugins) page of `mkdocs`
+ for more information about its plugin system.
+ """
+
+ css_filename: str = "assets/_mkdocstrings.css"
+ """The path of the CSS file to write in the site directory."""
+
+ def __init__(self) -> None:
+ """Initialize the object."""
+ super().__init__()
+ self._handlers: Handlers | None = None
+
+ @property
+ def handlers(self) -> Handlers:
+ """Get the instance of [mkdocstrings.Handlers][] for this plugin/build.
+
+ Raises:
+ RuntimeError: If the plugin hasn't been initialized with a config.
+
+ Returns:
+ An instance of [mkdocstrings.Handlers][] (the same throughout the build).
+ """
+ if not self._handlers:
+ raise RuntimeError("The plugin hasn't been initialized with a config yet")
+ return self._handlers
+
+ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
+ """Instantiate our Markdown extension.
+
+ Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
+ In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.MkdocstringsExtension]
+ and add it to the list of Markdown extensions used by `mkdocs`.
+
+ 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).
+
+ Arguments:
+ config: The MkDocs config object.
+
+ Returns:
+ The modified config.
+ """
+ if not self.plugin_enabled:
+ _logger.debug("Plugin is not enabled. Skipping.")
+ return config
+ _logger.debug("Adding extension to the list")
+
+ locale = self.config.locale or config.theme.get("language") or config.theme.get("locale") or "en"
+ locale = str(locale).replace("_", "-")
+
+ handlers = Handlers(
+ default=self.config.default_handler,
+ handlers_config=self.config.handlers,
+ theme=config.theme.name or os.path.dirname(config.theme.dirs[0]), # noqa: PTH120
+ custom_templates=self.config.custom_templates,
+ mdx=config.markdown_extensions,
+ mdx_config=config.mdx_configs,
+ inventory_project=config.site_name,
+ inventory_version="0.0.0", # TODO: Find a way to get actual version.
+ locale=locale,
+ tool_config=config,
+ )
+
+ handlers._download_inventories()
+
+ AutorefsPlugin.record_backlinks = True
+ autorefs: AutorefsPlugin
+ try:
+ # If autorefs plugin is explicitly enabled, just use it.
+ autorefs = config.plugins["autorefs"] # ty: ignore[invalid-assignment]
+ _logger.debug("Picked up existing autorefs instance %r", autorefs)
+ except KeyError:
+ # Otherwise, add a limited instance of it that acts only on what's added through `register_anchor`.
+ autorefs = AutorefsPlugin()
+ autorefs.config = AutorefsConfig() # ty:ignore[invalid-assignment]
+ autorefs.scan_toc = False
+ config.plugins["autorefs"] = autorefs
+ _logger.debug("Added a subdued autorefs instance %r", autorefs)
+
+ mkdocstrings_extension = MkdocstringsExtension(handlers, autorefs)
+ config.markdown_extensions.append(mkdocstrings_extension) # ty: ignore[invalid-argument-type]
+
+ config.extra_css.insert(0, self.css_filename) # So that it has lower priority than user files.
+
+ self._autorefs = autorefs
+ self._handlers = handlers
+ return config
+
+ @property
+ def inventory_enabled(self) -> bool:
+ """Tell if the inventory is enabled or not.
+
+ Returns:
+ Whether the inventory is enabled.
+ """
+ inventory_enabled = self.config.enable_inventory
+ if inventory_enabled is None:
+ inventory_enabled = any(handler.enable_inventory for handler in self.handlers.seen_handlers)
+ return inventory_enabled
+
+ @property
+ def plugin_enabled(self) -> bool:
+ """Tell if the plugin is enabled or not.
+
+ Returns:
+ Whether the plugin is enabled.
+ """
+ return self.config.enabled
+
+ @event_priority(50) # Early, before autorefs' starts applying cross-refs and collecting backlinks.
+ def _on_env_load_inventories(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None: # noqa: ARG002
+ if self.plugin_enabled and self._handlers:
+ register = config.plugins["autorefs"].register_url # ty: ignore[unresolved-attribute]
+ for identifier, url in self._handlers._yield_inventory_items():
+ register(identifier, url)
+
+ @event_priority(-20) # Late, not important.
+ def _on_env_add_css(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None: # noqa: ARG002
+ if self.plugin_enabled and self._handlers:
+ css_content = "\n".join(handler.extra_css for handler in self.handlers.seen_handlers)
+ write_file(css_content.encode("utf-8"), os.path.join(config.site_dir, self.css_filename)) # noqa: PTH118
+
+ @event_priority(-20) # Late, not important.
+ def _on_env_write_inventory(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None: # noqa: ARG002
+ if self.plugin_enabled and self._handlers and self.inventory_enabled:
+ _logger.debug("Creating inventory file objects.inv")
+ inv_contents = self.handlers.inventory.format_sphinx()
+ write_file(inv_contents, os.path.join(config.site_dir, "objects.inv")) # noqa: PTH118
+
+ @event_priority(-100) # Last, after autorefs has finished applying cross-refs and collecting backlinks.
+ def _on_env_apply_backlinks(self, env: Environment, /, *, config: MkDocsConfig, files: Files) -> Environment: # noqa: ARG002
+ regex = re.compile(r" tag from around the whole output.
-
- Returns:
- An HTML string.
- """
- treeprocessors = self._md.treeprocessors
- treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level # type: ignore[attr-defined]
- treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--" # type: ignore[attr-defined]
- treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph # type: ignore[attr-defined]
- try:
- return Markup(self._md.convert(text))
- finally:
- treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0 # type: ignore[attr-defined]
- treeprocessors[IdPrependingTreeprocessor.name].id_prefix = "" # type: ignore[attr-defined]
- treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False # type: ignore[attr-defined]
- self._md.reset()
-
- def do_heading(
- self,
- content: Markup,
- heading_level: int,
- *,
- role: str | None = None,
- hidden: bool = False,
- toc_label: str | None = None,
- **attributes: str,
- ) -> Markup:
- """Render an HTML heading and register it for the table of contents. For use inside templates.
-
- Arguments:
- content: The HTML within the heading.
- heading_level: The level of heading (e.g. 3 -> `h3`).
- role: An optional role for the object bound to this heading.
- hidden: If True, only register it for the table of contents, don't render anything.
- toc_label: The title to use in the table of contents ('data-toc-label' attribute).
- **attributes: Any extra HTML attributes of the heading.
-
- Returns:
- An HTML string.
- """
- # First, produce the "fake" heading, for ToC only.
- el = Element(f"h{heading_level}", attributes)
- if toc_label is None:
- toc_label = content.unescape() if isinstance(content, Markup) else content
- el.set("data-toc-label", toc_label)
- if role:
- el.set("data-role", role)
- self._headings.append(el)
-
- if hidden:
- return Markup('').format(attributes["id"])
-
- # Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.
- # Start with a heading that has just attributes (no text), and add a placeholder into it.
- el = Element(f"h{heading_level}", attributes)
- el.append(Element("mkdocstrings-placeholder"))
- # Tell the 'toc' extension to make its additions if configured so.
- toc = cast(TocTreeprocessor, self._md.treeprocessors["toc"])
- if toc.use_anchors:
- toc.add_anchor(el, attributes["id"])
- if toc.use_permalinks:
- toc.add_permalink(el, attributes["id"])
-
- # The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle
- # of the heading with a placeholder that can never occur (text can't directly contain angle brackets).
- # Now this HTML wrapper can be "filled" by replacing the placeholder.
- html_with_placeholder = tostring(el, encoding="unicode")
- assert ( # noqa: S101
- html_with_placeholder.count("