A Python handler for mkdocstrings.
[](https://github.com/mkdocstrings/python/actions?query=workflow%3Aci) -[](https://mkdocstrings.github.io/python/) +[](https://mkdocstrings.github.io/python/) [](https://pypi.org/project/mkdocstrings-python/) -[](https://gitpod.io/#https://github.com/mkdocstrings/python) +[](https://gitpod.io/#https://github.com/mkdocstrings/python) [](https://app.gitter.im/#/room/#python:gitter.im) --- diff --git a/config/git-changelog.toml b/config/git-changelog.toml index 44e2b1fb..57114e0c 100644 --- a/config/git-changelog.toml +++ b/config/git-changelog.toml @@ -6,3 +6,4 @@ parse-refs = false parse-trailers = true sections = ["build", "deps", "feat", "fix", "refactor"] template = "keepachangelog" +versioning = "pep440" diff --git a/config/pytest.ini b/config/pytest.ini index ebdeb484..9d75f5c6 100644 --- a/config/pytest.ini +++ b/config/pytest.ini @@ -1,8 +1,6 @@ [pytest] python_files = test_*.py - *_test.py - tests.py addopts = --cov --cov-config config/coverage.ini @@ -14,3 +12,6 @@ filterwarnings = error # TODO: remove once pytest-xdist 4 is released ignore:.*rsyncdir:DeprecationWarning:xdist + # TODO: remove once Griffe releases v1 + ignore:.*`get_logger`:DeprecationWarning:_griffe + ignore:.*`name`:DeprecationWarning:_griffe diff --git a/config/ruff.toml b/config/ruff.toml index 751bf595..e3c9ec30 100644 --- a/config/ruff.toml +++ b/config/ruff.toml @@ -3,8 +3,7 @@ line-length = 120 [lint] exclude = [ - "fixtures", - "site", + "tests/fixtures/*.py", ] select = [ "A", "ANN", "ARG", @@ -78,5 +77,8 @@ known-first-party = ["mkdocstrings_handlers.python"] convention = "google" [format] +exclude = [ + "tests/fixtures/*.py", +] docstring-code-format = true docstring-code-line-length = 80 diff --git a/config/vscode/tasks.json b/config/vscode/tasks.json index 30008cf2..73145eec 100644 --- a/config/vscode/tasks.json +++ b/config/vscode/tasks.json @@ -31,12 +31,6 @@ "command": "scripts/make", "args": ["check-docs"] }, - { - "label": "check-dependencies", - "type": "process", - "command": "scripts/make", - "args": ["check-dependencies"] - }, { "label": "check-api", "type": "process", diff --git a/devdeps.txt b/devdeps.txt index 4fe97996..e0afd7e2 100644 --- a/devdeps.txt +++ b/devdeps.txt @@ -1,27 +1,32 @@ -build>=1.0 -duty>=0.10 -black>=23.9 -markdown-callouts>=0.3 -markdown-exec>=1.7 -mkdocs>=1.5 +# dev +editables>=0.5 + +# maintenance +build>=1.2 +git-changelog>=2.5 +twine>=5.0; python_version < '3.13' + +# ci +duty>=1.4 +ruff>=0.4 +pytest>=8.2 +pytest-cov>=5.0 +pytest-randomly>=3.15 +pytest-xdist>=3.6 +mypy>=1.10 +types-markdown>=3.6 +types-pyyaml>=6.0 + +# docs +black>=24.4 +markdown-callouts>=0.4 +markdown-exec>=1.8 +mkdocs>=1.6 mkdocs-coverage>=1.0 mkdocs-gen-files>=0.5 -mkdocs-git-committers-plugin-2>=1.2 +mkdocs-git-committers-plugin-2>=2.3 mkdocs-literate-nav>=0.6 -mkdocs-material>=9.4 -mkdocs-minify-plugin>=0.7 -mkdocstrings[python]>=0.23 +mkdocs-material>=9.5 +mkdocs-minify-plugin>=0.8 +mkdocstrings[python]>=0.25 tomli>=2.0; python_version < '3.11' -black>=23.9 -blacken-docs>=1.16 -git-changelog>=2.3 -ruff>=0.0 -pytest>=7.4 -pytest-cov>=4.1 -pytest-randomly>=3.15 -pytest-xdist>=3.3 -mypy>=1.5 -types-markdown>=3.5 -types-pyyaml>=6.0 -safety>=2.3 -twine>=5.0 diff --git a/docs/.overrides/main.html b/docs/.overrides/main.html index cf8adeb7..1e956857 100644 --- a/docs/.overrides/main.html +++ b/docs/.overrides/main.html @@ -2,17 +2,19 @@ {% block announce %} - Sponsorship - is now available! + Fund this project through + sponsorship {% include ".icons/octicons/heart-fill-16.svg" %} — - For updates follow @pawamoy on + Follow + @pawamoy on {% include ".icons/fontawesome/brands/mastodon.svg" %} Fosstodon + for updates {% endblock %} diff --git a/docs/.overrides/partials/comments.html b/docs/.overrides/partials/comments.html new file mode 100644 index 00000000..0dedc405 --- /dev/null +++ b/docs/.overrides/partials/comments.html @@ -0,0 +1,57 @@ + + + \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 612c7a5e..8e6f2fb4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,6 @@ +--- +hide: +- feedback +--- + --8<-- "README.md" diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 123fe42d..3bc3aa56 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -99,6 +99,10 @@ with your GitHub account, visit [pawamoy's sponsor profile][github sponsor profi and complete a sponsorship of **$10 a month or more**. You can use your individual or organization GitHub account for sponsoring. +Sponsorships lower than $10 a month are also very much appreciated, and useful. +They won't grant you access to Insiders, but they will be counted towards reaching sponsorship goals. +*Every* sponsorship helps us implementing new features and releasing them to the public. + **Important**: If you're sponsoring **[@pawamoy][github sponsor profile]** through a GitHub organization, please send a short email to insiders@pawamoy.fr with the name of your diff --git a/docs/insiders/installation.md b/docs/insiders/installation.md index 3ebe5dfd..0e4628ca 100644 --- a/docs/insiders/installation.md +++ b/docs/insiders/installation.md @@ -23,6 +23,9 @@ of Insiders projects in the PyPI index of your choice See [how to install it](https://pawamoy.github.io/pypi-insiders/#installation) and [how to use it](https://pawamoy.github.io/pypi-insiders/#usage). +**We kindly ask that you do not upload the distributions to public registries, +as it is against our [Terms of use](index.md#terms).** + ### with pip (ssh/https) *mkdocstrings-python Insiders* can be installed with `pip` [using SSH][using ssh]: @@ -58,130 +61,15 @@ pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/mkdocstrings-pyt > 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-python* 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-python/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).** +### with Git ->? 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-python -> cd mkdocstrings-python -> -> # 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-python`, -> 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-python Insiders* directly from `git`: +Of course, you can use *mkdocstrings-python Insiders* directly using Git: ``` git clone git@github.com:pawamoy-insiders/mkdocstrings-python ``` -When cloning from `git`, the package must be installed: +When cloning with Git, the package must be installed: ``` pip install -e mkdocstrings-python 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/license.md b/docs/license.md index a873d2b5..e81c0edf 100644 --- a/docs/license.md +++ b/docs/license.md @@ -1,3 +1,8 @@ +--- +hide: +- feedback +--- + # License ``` diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md index fcb9a19a..027ebaed 100644 --- a/docs/usage/configuration/docstrings.md +++ b/docs/usage/configuration/docstrings.md @@ -120,7 +120,7 @@ class PrintOK: """Initialize the instance. Examples: - >>> Class() # doctest: +NORMALIZE_WHITESPACE + >>> PrintOK() # doctest: +NORMALIZE_WHITESPACE ok """ print("ok") @@ -136,7 +136,7 @@ class PrintOK:Examples:
```pycon ->>> Class() +>>> PrintOK() ok ``` //// @@ -149,7 +149,7 @@ okExamples:
```pycon ->>> Class() # doctest: +NORMALIZE_WHITESPACE +>>> PrintOK() # doctest: +NORMALIZE_WHITESPACE ok ``` //// @@ -208,8 +208,8 @@ In that case, the Spacy tables can help. **Type** | **Name** | **Description** | **Default** ---------- | ----------- | ------------------------ | ----------- -list[int \| float] | `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | *required*
-VacuumType \| Literal["regular"] | `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | `VacuumType.PLASMA`
+list [int \| float ]VacuumType \| Literal ["regular"]list[int \| float]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-- `vacuum_type` (VacuumType \| Literal["regular"]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+- `gravity_forces` (list [int \| float ]VacuumType \| Literal ["regular"]list[int \| float] DEFAULT: required
-`vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.VacuumType \| Literal["regular"] DEFAULT: VacuumType.PLASMA
+`gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.list [int \| float ]VacuumType \| Literal ["regular"]VacuumType.PLASMA
////
///
diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md
index e4ddaec1..d8d7f250 100644
--- a/docs/usage/configuration/general.md
+++ b/docs/usage/configuration/general.md
@@ -139,7 +139,7 @@ def some_function():
## `preload_modules`
-- **:octicons-package-24: Type list[str] | None :material-equal: `None`{ title="default value" }**
+- **:octicons-package-24: Type list [str ] | Nonelist[str] |
- bool | None :material-equal: `None`{ title="default value" }**
+- **:octicons-package-24: Type list [str ] |
+ bool | Nonelist[str] |
- bool :material-equal: `False`{ title="default value" }**
+- **:octicons-package-24: Type list [str ] |
+ bool list[str] | None :material-equal: `["!^_[^_]"]`{ title="default value" }**
+- **:octicons-package-24: Type list [str ] | Nonebool | dict[str, bool] :material-equal: `False`{ title="default value" }**
+- **:octicons-package-24: Type bool | dict [str , bool ]{{ class_name }}
- {% endif %}
- {% endblock heading %}
-
- {% block labels scoped %}
- {% with labels = class.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
- {% endblock labels %}
-
- {% endfilter %}
-
- {% block signature scoped %}
- {% if config.separate_signature and config.merge_init_into_class %}
- {% if "__init__" in class.all_members %}
- {% with function = class.all_members["__init__"] %}
- {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
- {{ class.name }}
- {% endfilter %}
- {% endwith %}
- {% endif %}
- {% endif %}
- {% endblock signature %}
-
- {% else %}
- {% if config.show_root_toc_entry %}
- {% filter heading(heading_level,
- role="class",
- id=html_id,
- toc_label=('
- Bases: {% for expression in class.bases -%}
- {% include "expression.html" with context %}{% if not loop.last %}, {% endif %}
- {% endfor -%}
-
- {%- if init.relative_filepath.is_absolute() -%}
- {{ init.relative_package_filepath }}
- {%- else -%}
- {{ init.relative_filepath }}
- {%- endif -%}
-
- {%- if class.relative_filepath.is_absolute() -%}
- {{ class.relative_package_filepath }}
- {%- else -%}
- {{ class.relative_filepath }}
- {%- endif -%}
- {{ class_name }}
+ {% endif %}
+ {% endblock heading %}
+
+ {% block labels scoped %}
+ {#- Labels block.
+
+ This block renders the labels for the class.
+ -#}
+ {% with labels = class.labels %}
+ {% include "labels"|get_template with context %}
+ {% endwith %}
+ {% endblock labels %}
+
+ {% endfilter %}
+
+ {% block signature scoped %}
+ {#- Signature block.
+
+ This block renders the signature for the class.
+ -#}
+ {% if config.separate_signature and config.merge_init_into_class %}
+ {% if "__init__" in class.all_members %}
+ {% with function = class.all_members["__init__"] %}
+ {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+ {{ class.name }}
+ {% endfilter %}
+ {% endwith %}
+ {% endif %}
+ {% endif %}
+ {% endblock signature %}
+
+ {% else %}
+ {% if config.show_root_toc_entry %}
+ {% filter heading(heading_level,
+ role="class",
+ id=html_id,
+ toc_label=('
+ Bases: {% for expression in class.bases -%}
+ {% include "expression"|get_template with context %}{% if not loop.last %}, {% endif %}
+ {% endfor -%}
+
+ {%- if init.relative_filepath.is_absolute() -%}
+ {{ init.relative_package_filepath }}
+ {%- else -%}
+ {{ init.relative_filepath }}
+ {%- endif -%}
+
+ {%- if class.relative_filepath.is_absolute() -%}
+ {{ class.relative_package_filepath }}
+ {%- else -%}
+ {{ class.relative_filepath }}
+ {%- endif -%}
+ {{ section.title or lang.t("Attributes:") }}
-| {{ lang.t("Name") }} | -{{ lang.t("Type") }} | -{{ lang.t("Description") }} | -
|---|---|---|
{{ attribute.name }} |
-
- {% if attribute.annotation %}
- {% with expression = attribute.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ attribute.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Attributes:") }}
-{{ attribute.name }}
- {% if attribute.annotation %}
- {% with expression = attribute.annotation %}
- ({% include "expression.html" with context %})
- {% endwith %}
- {% endif %}
- –
- | {{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
{{ attribute.name }} |
-
-
- {{ attribute.description|convert_markdown(heading_level, html_id) }}
-
-
- {% if attribute.annotation %}
-
- TYPE:
- {% with expression = attribute.annotation %}
- |
-
{{ section.title or lang.t("Attributes:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
|
+
+ {% if attribute.annotation %}
+ {% with expression = attribute.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ attribute.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Attributes:") }}
+{{ attribute.name }} {% include "expression"|get_template with context %})
+ {% endwith %}
+ {% endif %}
+ –
+ | {{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ attribute.description|convert_markdown(heading_level, html_id) }}
+
+
+ {% if attribute.annotation %}
+
+ TYPE:
+ {% with expression = attribute.annotation %}
+ |
+
{{ section.title or lang.t("Classes:") }}
-| {{ lang.t("Name") }} | -{{ lang.t("Description") }} | -
|---|---|
{{ class.name }} |
-
-
- {{ class.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Classes:") }}
-{{ class.name }}
- –
- | {{ (section.title or lang.t("CLASS")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
{{ class.name }} |
-
-
- {{ class.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Classes:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
|
+
+
+ {{ class.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Classes:") }}
+{{ class.name }} | {{ (section.title or lang.t("CLASS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ class.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Examples:") }}
-{% for section_type, sub_section in section.value %} - {% if section_type.value == "text" %} - {{ sub_section|convert_markdown(heading_level, html_id) }} - {% elif section_type.value == "examples" %} - {{ sub_section|highlight(language="pycon", linenums=False) }} - {% endif %} -{% endfor %} +{% block logs scoped %} + {{ super() }} + {# TODO: Switch to a warning after some time. #} + {{ log.info( + "DeprecationWarning: Extending '_base/docstring/examples.html' is deprecated, extend '_base/docstring/examples.html.jinja' instead. " ~ + "After some time, this message will be logged as a warning, causing strict builds to fail.", + once=True, + ) }} +{% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja new file mode 100644 index 00000000..39a90fa0 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja @@ -0,0 +1,28 @@ +{#- Template for "Examples" sections in docstrings. + +This template renders a list of documented examples. +It alternates between rendering text and code examples. + +Context: + section (griffe.DocstringSectionAttributes): The section to render. +-#} + +{% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} + {{ log.debug("Rendering examples section") }} +{% endblock logs %} + +{% import "language"|get_template as lang with context %} +{#- Language module providing the `t` translation method. -#} + +{{ section.title or lang.t("Examples:") }}
+{% for section_type, sub_section in section.value %} + {% if section_type.value == "text" %} + {{ sub_section|convert_markdown(heading_level, html_id) }} + {% elif section_type.value == "examples" %} + {{ sub_section|highlight(language="pycon", linenums=False) }} + {% endif %} +{% endfor %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html index ab1939f5..a61c48fb 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html @@ -1,73 +1,11 @@ -{{ log.debug("Rendering functions section") }} +{% extends "_base/docstring/functions.html.jinja" %} -{% import "language.html" as lang with context %} - -{% if config.docstring_section_style == "table" %} - {% block table_style scoped %} -{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
-| {{ lang.t("Name") }} | -{{ lang.t("Description") }} | -
|---|---|
{{ function.name }} |
-
-
- {{ function.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
-{{ function.name }}
- –
- | {{ (section.title or lang.t("METHOD") if obj.is_class else lang.t("FUNCTION")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
{{ function.name }} |
-
-
- {{ function.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
|
+
+
+ {{ function.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
+{{ function.name }} | {{ (section.title or lang.t("METHOD") if obj.is_class else lang.t("FUNCTION")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ function.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Modules:") }}
-| {{ lang.t("Name") }} | -{{ lang.t("Description") }} | -
|---|---|
{{ module.name }} |
-
-
- {{ module.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Modules:") }}
-{{ module.name }}
- –
- | {{ (section.title or lang.t("MODULE")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
{{ module.name }} |
-
-
- {{ module.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Modules:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
|
+
+
+ {{ module.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Modules:") }}
+{{ module.name }} | {{ (section.title or lang.t("MODULE")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ module.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Other Parameters:") }}
-| {{ lang.t("Name") }} | -{{ lang.t("Type") }} | -{{ lang.t("Description") }} | -
|---|---|---|
{{ parameter.name }} |
-
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Other Parameters:") }}
-{{ parameter.name }}
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- ({% include "expression.html" with context %})
- {% endwith %}
- {% endif %}
- –
- | {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
{{ parameter.name }} |
-
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
-
- {% if parameter.annotation %}
-
- {{ lang.t("TYPE:") }}
- {% with expression = parameter.annotation %}
- |
-
{{ section.title or lang.t("Other Parameters:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
{{ parameter.name }} |
+
+ {% if parameter.annotation %}
+ {% with expression = parameter.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Other Parameters:") }}
+{{ parameter.name }}
+ {% if parameter.annotation %}
+ {% with expression = parameter.annotation %}
+ ({% include "expression"|get_template with context %})
+ {% endwith %}
+ {% endif %}
+ –
+ | {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
{{ parameter.name }} |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id) }}
+
+
+ {% if parameter.annotation %}
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = parameter.annotation %}
+ |
+
{{ section.title or lang.t("Parameters:") }}
-| {{ lang.t("Name") }} | -{{ lang.t("Type") }} | -{{ lang.t("Description") }} | -{{ lang.t("Default") }} | -
|---|---|---|---|
{{ parameter.name }} |
-
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
- |
-
- {% if parameter.default %}
- {% with expression = parameter.default %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% else %}
- {{ lang.t("required") }}
- {% endif %}
- |
-
{{ section.title or lang.t("Parameters:") }}
-{{ parameter.name }}
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- ({% include "expression.html" with context %}
- {%- if parameter.default %}, {{ lang.t("default:") }}
- {% with expression = parameter.default %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %})
- {% endwith %}
- {% endif %}
- –
- | {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
{{ parameter.name }} |
-
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
-
- {% if parameter.annotation %}
-
- {{ lang.t("TYPE:") }}
- {% with expression = parameter.annotation %}
- |
-
{{ section.title or lang.t("Parameters:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +{{ lang.t("Default") }} | +
|---|---|---|---|
{{ parameter.name }} |
+
+ {% if parameter.annotation %}
+ {% with expression = parameter.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
+ {% if parameter.default %}
+ {% with expression = parameter.default %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% else %}
+ {{ lang.t("required") }}
+ {% endif %}
+ |
+
{{ section.title or lang.t("Parameters:") }}
+{{ parameter.name }}
+ {% if parameter.annotation %}
+ {% with expression = parameter.annotation %}
+ ({% include "expression"|get_template with context %}
+ {%- if parameter.default %}, {{ lang.t("default:") }}
+ {% with expression = parameter.default %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %})
+ {% endwith %}
+ {% endif %}
+ –
+ | {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
{{ parameter.name }} |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id) }}
+
+
+ {% if parameter.annotation %}
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = parameter.annotation %}
+ |
+
{{ section.title or lang.t("Raises:") }}
-| {{ lang.t("Type") }} | -{{ lang.t("Description") }} | -
|---|---|
- {% if raises.annotation %}
- {% with expression = raises.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ raises.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ lang.t(section.title) or lang.t("Raises:") }}
-{% include "expression.html" with context %}
- {% endwith %}
- –
- {% endif %}
- | {{ (section.title or lang.t("RAISES")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
-
- {% with expression = raises.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- |
-
-
- {{ raises.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Raises:") }}
+| {{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|
+ {% if raises.annotation %}
+ {% with expression = raises.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ raises.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ lang.t(section.title) or lang.t("Raises:") }}
+{% include "expression"|get_template with context %}
+ {% endwith %}
+ –
+ {% endif %}
+ | {{ (section.title or lang.t("RAISES")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+
+ {% with expression = raises.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ |
+
+
+ {{ raises.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Receives:") }}
-| {{ lang.t("Name") }} | {% endif %} -{{ lang.t("Type") }} | -{{ lang.t("Description") }} | -
|---|---|---|
{% if receives.name %}{{ receives.name }}{% endif %} | {% endif %}
-
- {% if receives.annotation %}
- {% with expression = receives.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ receives.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Receives:") }}
-{{ receives.name }}{% endif %}
- {% if receives.annotation %}
- {% with expression = receives.annotation %}
- {% if receives.name %} ({% endif %}
- {% include "expression.html" with context %}
- {% if receives.name %}){% endif %}
- {% endwith %}
- {% endif %}
- –
- | {{ (section.title or lang.t("RECEIVES")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
- {% if receives.name %}
- {{ receives.name }}
- {% elif receives.annotation %}
-
- {% with expression = receives.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
-
- {{ receives.description|convert_markdown(heading_level, html_id) }}
-
- {% if receives.name and receives.annotation %}
-
-
- {{ lang.t("TYPE:") }}
- {% with expression = receives.annotation %}
- |
-
{{ section.title or lang.t("Receives:") }}
+| {{ lang.t("Name") }} | {% endif %} +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
{% if receives.name %}{{ receives.name }}{% endif %} | {% endif %}
+
+ {% if receives.annotation %}
+ {% with expression = receives.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ receives.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Receives:") }}
+{{ receives.name }}{% endif %}
+ {% if receives.annotation %}
+ {% with expression = receives.annotation %}
+ {% if receives.name %} ({% endif %}
+ {% include "expression"|get_template with context %}
+ {% if receives.name %}){% endif %}
+ {% endwith %}
+ {% endif %}
+ –
+ | {{ (section.title or lang.t("RECEIVES")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+ {% if receives.name %}
+ {{ receives.name }}
+ {% elif receives.annotation %}
+
+ {% with expression = receives.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ receives.description|convert_markdown(heading_level, html_id) }}
+
+ {% if receives.name and receives.annotation %}
+
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = receives.annotation %}
+ |
+
{{ section.title or lang.t("Returns:") }}
-| {{ lang.t("Name") }} | {% endif %} -{{ lang.t("Type") }} | -{{ lang.t("Description") }} | -
|---|---|---|
{% if returns.name %}{{ returns.name }}{% endif %} | {% endif %}
-
- {% if returns.annotation %}
- {% with expression = returns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ returns.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Returns:") }}
-{{ returns.name }}{% endif %}
- {% if returns.annotation %}
- {% with expression = returns.annotation %}
- {% if returns.name %} ({% endif %}
- {% include "expression.html" with context %}
- {% if returns.name %}){% endif %}
- {% endwith %}
- {% endif %}
- –
- | {{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION").upper() }} | -
|---|---|
- {% if returns.name %}
- {{ returns.name }}
- {% elif returns.annotation %}
-
- {% with expression = returns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
-
- {{ returns.description|convert_markdown(heading_level, html_id) }}
-
- {% if returns.name and returns.annotation %}
-
-
- {{ lang.t("TYPE:") }}
- {% with expression = returns.annotation %}
- |
-
{{ section.title or lang.t("Returns:") }}
+| {{ lang.t("Name") }} | {% endif %} +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
{% if returns.name %}{{ returns.name }}{% endif %} | {% endif %}
+
+ {% if returns.annotation %}
+ {% with expression = returns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ returns.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Returns:") }}
+{{ returns.name }}{% endif %}
+ {% if returns.annotation %}
+ {% with expression = returns.annotation %}
+ {% if returns.name %} ({% endif %}
+ {% include "expression"|get_template with context %}
+ {% if returns.name %}){% endif %}
+ {% endwith %}
+ {% endif %}
+ –
+ | {{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION").upper() }} | +
|---|---|
+ {% if returns.name %}
+ {{ returns.name }}
+ {% elif returns.annotation %}
+
+ {% with expression = returns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ returns.description|convert_markdown(heading_level, html_id) }}
+
+ {% if returns.name and returns.annotation %}
+
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = returns.annotation %}
+ |
+
{{ section.title or lang.t("Warns:") }}
-| {{ lang.t("Type") }} | -{{ lang.t("Description") }} | -
|---|---|
- {% if warns.annotation %}
- {% with expression = warns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ warns.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Warns:") }}
-{% include "expression.html" with context %}
- {% endwith %}
- –
- {% endif %}
- | {{ (section.title or lang.t("WARNS")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
-
- {% with expression = warns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- |
-
-
- {{ warns.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Warns:") }}
+| {{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|
+ {% if warns.annotation %}
+ {% with expression = warns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ warns.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Warns:") }}
+{% include "expression"|get_template with context %}
+ {% endwith %}
+ –
+ {% endif %}
+ | {{ (section.title or lang.t("WARNS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+
+ {% with expression = warns.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ |
+
+
+ {{ warns.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Yields:") }}
-| {{ lang.t("Name") }} | {% endif %} -{{ lang.t("Type") }} | -{{ lang.t("Description") }} | -
|---|---|---|
{% if yields.name %}{{ yields.name }}{% endif %} | {% endif %}
-
- {% if yields.annotation %}
- {% with expression = yields.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
-
-
- {{ yields.description|convert_markdown(heading_level, html_id) }}
-
- |
-
{{ section.title or lang.t("Yields:") }}
-{{ yields.name }}{% endif %}
- {% if yields.annotation %}
- {% with expression = yields.annotation %}
- {% if yields.name %} ({% endif %}
- {% include "expression.html" with context %}
- {% if yields.name %}){% endif %}
- {% endwith %}
- {% endif %}
- –
- | {{ (section.title or lang.t("YIELDS")).rstrip(":").upper() }} | -{{ lang.t("DESCRIPTION") }} | -
|---|---|
- {% if yields.name %}
- {{ yields.name }}
- {% elif yields.annotation %}
-
- {% with expression = yields.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
-
- {{ yields.description|convert_markdown(heading_level, html_id) }}
-
- {% if yields.name and yields.annotation %}
-
-
- {{ lang.t("TYPE:") }}:
- {% with expression = yields.annotation %}
- |
-
{{ section.title or lang.t("Yields:") }}
+| {{ lang.t("Name") }} | {% endif %} +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
{% if yields.name %}{{ yields.name }}{% endif %} | {% endif %}
+
+ {% if yields.annotation %}
+ {% with expression = yields.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ yields.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Yields:") }}
+{{ yields.name }}{% endif %}
+ {% if yields.annotation %}
+ {% with expression = yields.annotation %}
+ {% if yields.name %} ({% endif %}
+ {% include "expression"|get_template with context %}
+ {% if yields.name %}){% endif %}
+ {% endwith %}
+ {% endif %}
+ –
+ | {{ (section.title or lang.t("YIELDS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+ {% if yields.name %}
+ {{ yields.name }}
+ {% elif yields.annotation %}
+
+ {% with expression = yields.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ yields.description|convert_markdown(heading_level, html_id) }}
+
+ {% if yields.name and yields.annotation %}
+
+
+ {{ lang.t("TYPE:") }}:
+ {% with expression = yields.annotation %}
+ |
+
- {%- if function.relative_filepath.is_absolute() -%}
- {{ function.relative_package_filepath }}
- {%- else -%}
- {{ function.relative_filepath }}
- {%- endif -%}
-
+ {%- if function.relative_filepath.is_absolute() -%}
+ {{ function.relative_package_filepath }}
+ {%- else -%}
+ {{ function.relative_filepath }}
+ {%- endif -%}
+ {{ label }}
- {% endfor %}
-
-{% endif %}
+{% extends "_base/labels.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/labels.html' is deprecated, extend '_base/labels.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
new file mode 100644
index 00000000..dced4913
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
@@ -0,0 +1,25 @@
+{#- Template for object labels.
+
+Labels are additional information that can be displayed alongside an object.
+Example labels include "property", "writable" or "cached" for properties,
+"classmethod" or "staticmethod" for methods, etc.
+
+Context:
+ labels (list): The list of labels to render.
+ config (dict): The configuration options.
+-#}
+
+{% if config.show_labels and labels %}
+ {% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering labels") }}
+ {% endblock logs %}
+
+ {% for label in labels|sort %}
+ {{ label }}
+ {% endfor %}
+
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html b/src/mkdocstrings_handlers/python/templates/material/_base/language.html
new file mode 100644
index 00000000..c97d0c31
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html
@@ -0,0 +1,11 @@
+{% extends "_base/language.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/language.html' is deprecated, extend '_base/language.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
new file mode 100644
index 00000000..5b643726
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
@@ -0,0 +1,18 @@
+{#- Import translation macros for the given language and fallback language. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% set lang_pth = "languages/" ~ locale | get_template %}
+{% if lang_pth is existing_template %}
+ {% import lang_pth as lang %}
+ {% import "languages/en"|get_template as fallback %}
+ {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %}
+{% else %}
+ {% import "languages/en"|get_template as lang %}
+ {% macro t(key) %}{{ lang.t(key) }}{% endmacro %}
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html
index 1f76e059..eab87415 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html
@@ -1,37 +1,11 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "ATTRIBUTE",
- "Attributes:": "Attributes:",
- "Classes:": "Classes:",
- "CLASS": "CLASS",
- "DEFAULT:": "DEFAULT:",
- "Default": "Default",
- "default:": "default:",
- "DESCRIPTION": "DESCRIPTION",
- "Description": "Description",
- "Examples:": "Examples:",
- "Functions:": "Functions:",
- "FUNCTION": "FUNCTION",
- "Methods:": "Methods:",
- "METHOD": "METHOD",
- "Modules:": "Modules:",
- "MODULE": "MODULE",
- "Name": "Name",
- "Other Parameters:": "Other Parameters:",
- "PARAMETER": "PARAMETER",
- "Parameters:": "Parameters:",
- "RAISES": "RAISES",
- "Raises:" : "Raises:",
- "RECEIVES": "RECEIVES",
- "Receives:": "Receives:",
- "required": "required",
- "RETURNS": "RETURNS",
- "Returns:": "Returns:",
- "Source code in": "Source code in",
- "TYPE:": "TYPE:",
- "Type": "Type",
- "WARNS": "WARNS",
- "Warns:": "Warns:",
- "YIELDS": "YIELDS",
- "Yields:": "Yields:",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/en.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/en.html' is deprecated, extend '_base/languages/en.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja
new file mode 100644
index 00000000..d988b6ab
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja
@@ -0,0 +1,45 @@
+{#- Macro for English translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "ATTRIBUTE",
+ "Attributes:": "Attributes:",
+ "Classes:": "Classes:",
+ "CLASS": "CLASS",
+ "DEFAULT:": "DEFAULT:",
+ "Default": "Default",
+ "default:": "default:",
+ "DESCRIPTION": "DESCRIPTION",
+ "Description": "Description",
+ "Examples:": "Examples:",
+ "Functions:": "Functions:",
+ "FUNCTION": "FUNCTION",
+ "Methods:": "Methods:",
+ "METHOD": "METHOD",
+ "Modules:": "Modules:",
+ "MODULE": "MODULE",
+ "Name": "Name",
+ "Other Parameters:": "Other Parameters:",
+ "PARAMETER": "PARAMETER",
+ "Parameters:": "Parameters:",
+ "RAISES": "RAISES",
+ "Raises:" : "Raises:",
+ "RECEIVES": "RECEIVES",
+ "Receives:": "Receives:",
+ "required": "required",
+ "RETURNS": "RETURNS",
+ "Returns:": "Returns:",
+ "Source code in": "Source code in",
+ "TYPE:": "TYPE:",
+ "Type": "Type",
+ "WARNS": "WARNS",
+ "Warns:": "Warns:",
+ "YIELDS": "YIELDS",
+ "Yields:": "Yields:",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html
index 456e1170..14319499 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html
@@ -1,37 +1,11 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "属性",
- "Attributes:": "属性：",
- "Classes:": "",
- "CLASS": "",
- "DEFAULT:": "デフォルト：",
- "Default": "デフォルト",
- "default:": "デフォルト：",
- "DESCRIPTION": "デスクリプション",
- "Description": "デスクリプション",
- "Examples:": "例：",
- "Functions:": "",
- "FUNCTION": "",
- "Methods:": "",
- "METHOD": "",
- "Modules:": "",
- "MODULE": "",
- "Name": "名前",
- "Other Parameters:": "他の引数：",
- "PARAMETER": "引数",
- "Parameters:": "引数：",
- "RAISES": "発生",
- "Raises:" : "発生：",
- "RECEIVES": "取得",
- "Receives:": "取得：",
- "required": "必須",
- "RETURNS": "戻り値",
- "Returns:": "戻り値：",
- "Source code in": "ソースコード位置：",
- "TYPE:": "タイプ：",
- "Type": "タイプ",
- "WARNS": "警告",
- "Warns:": "警告：",
- "YIELDS": "返す",
- "Yields:": "返す：",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/ja.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/ja.html' is deprecated, extend '_base/languages/ja.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja
new file mode 100644
index 00000000..a6b7728b
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja
@@ -0,0 +1,45 @@
+{#- Macro for Japanese translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "属性",
+ "Attributes:": "属性：",
+ "Classes:": "",
+ "CLASS": "",
+ "DEFAULT:": "デフォルト：",
+ "Default": "デフォルト",
+ "default:": "デフォルト：",
+ "DESCRIPTION": "デスクリプション",
+ "Description": "デスクリプション",
+ "Examples:": "例：",
+ "Functions:": "",
+ "FUNCTION": "",
+ "Methods:": "",
+ "METHOD": "",
+ "Modules:": "",
+ "MODULE": "",
+ "Name": "名前",
+ "Other Parameters:": "他の引数：",
+ "PARAMETER": "引数",
+ "Parameters:": "引数：",
+ "RAISES": "発生",
+ "Raises:" : "発生：",
+ "RECEIVES": "取得",
+ "Receives:": "取得：",
+ "required": "必須",
+ "RETURNS": "戻り値",
+ "Returns:": "戻り値：",
+ "Source code in": "ソースコード位置：",
+ "TYPE:": "タイプ：",
+ "Type": "タイプ",
+ "WARNS": "警告",
+ "Warns:": "警告：",
+ "YIELDS": "返す",
+ "Yields:": "返す：",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html
index 9c018f27..0b281195 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html
@@ -1,37 +1,11 @@
-
-{% macro t(key) %}{{ {
- "ATTRIBUTE": "属性",
- "Attributes:": "属性：",
- "Classes:": "",
- "CLASS": "",
- "DEFAULT:": "默认：",
- "Default": "默认",
- "default:": "默认：",
- "DESCRIPTION": "描述",
- "Description": "描述",
- "Examples:": "示例：",
- "Functions:": "",
- "FUNCTION": "",
- "Methods:": "",
- "METHOD": "",
- "Modules:": "",
- "MODULE": "",
- "Name": "名称",
- "Other Parameters:": "其他参数：",
- "PARAMETER": "参数",
- "Parameters:": "参数：",
- "RAISES": "引发",
- "Raises:" : "引发：",
- "Receives:": "接收：",
- "RECEIVES": "接收",
- "required": "必需",
- "RETURNS": "返回",
- "Returns:": "返回：",
- "Source code in": "源代码位于：",
- "TYPE:": "类型：",
- "Type": "类型",
- "Warns:": "警告：",
- "WARNS": "警告",
- "YIELDS": "产生",
- "Yields:": "产生：",
-}[key] }}{% endmacro %}
\ No newline at end of file
+{% extends "_base/languages/zh.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/languages/zh.html' is deprecated, extend '_base/languages/zh.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja
new file mode 100644
index 00000000..f748b83c
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja
@@ -0,0 +1,45 @@
+{#- Macro for Chinese translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "属性",
+ "Attributes:": "属性：",
+ "Classes:": "",
+ "CLASS": "",
+ "DEFAULT:": "默认：",
+ "Default": "默认",
+ "default:": "默认：",
+ "DESCRIPTION": "描述",
+ "Description": "描述",
+ "Examples:": "示例：",
+ "Functions:": "",
+ "FUNCTION": "",
+ "Methods:": "",
+ "METHOD": "",
+ "Modules:": "",
+ "MODULE": "",
+ "Name": "名称",
+ "Other Parameters:": "其他参数：",
+ "PARAMETER": "参数",
+ "Parameters:": "参数：",
+ "RAISES": "引发",
+ "Raises:" : "引发：",
+ "Receives:": "接收：",
+ "RECEIVES": "接收",
+ "required": "必需",
+ "RETURNS": "返回",
+ "Returns:": "返回：",
+ "Source code in": "源代码位于：",
+ "TYPE:": "类型：",
+ "Type": "类型",
+ "Warns:": "警告：",
+ "WARNS": "警告",
+ "YIELDS": "产生",
+ "Yields:": "产生：",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html b/src/mkdocstrings_handlers/python/templates/material/_base/module.html
index 7d45e321..918ab6d0 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html
@@ -1,74 +1,11 @@
-{{ log.debug("Rendering " + module.path) }}
-
-{{ module_name }}
- {% endif %}
- {% endblock heading %}
-
- {% block labels scoped %}
- {% with labels = module.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
- {% endblock labels %}
-
- {% endfilter %}
-
- {% else %}
- {% if config.show_root_toc_entry %}
- {% filter heading(heading_level,
- role="module",
- id=html_id,
- toc_label=('{{ module_name }}
+ {% endif %}
+ {% endblock heading %}
+
+ {% block labels scoped %}
+ {#- Labels block.
+
+ This block renders the labels for the module.
+ -#}
+ {% with labels = module.labels %}
+ {% include "labels"|get_template with context %}
+ {% endwith %}
+ {% endblock labels %}
+
+ {% endfilter %}
+
+ {% else %}
+ {% if config.show_root_toc_entry %}
+ {% filter heading(heading_level,
+ role="module",
+ id=html_id,
+ toc_label=('| {{ section.title or lang.t("Attributes:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Other parameters:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Parameters:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Raises:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Receives:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Returns:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Warns:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Yields:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Attributes:") }} | -
-
|
-
|---|
| {{ section.title or lang.t("Other parameters:") }} | -
-
|
-
|---|
| {{ section.title or lang.t("Parameters:") }} | -
-
|
-
|---|
| {{ section.title or lang.t("Raises:") }} | -
-
|
-
|---|
| {{ section.title or lang.t("Receives:") }} | -
-
|
-
|---|
| {{ section.title or lang.t("Returns:") }} | -
-
|
-
|---|
| {{ section.title or lang.t("Warns:") }} | -
-
|
-
|---|
| {{ section.title or lang.t("Yields:") }} | -
-
|
-
|---|
This is an example.
" in rendered @@ -145,3 +146,29 @@ def test_extension_paths(tmp_path: Path, expect_change: bool, extension: str | d raise ValueError("Normalization must not change extension items type") else: assert normalized == extension + + +def test_rendering_object_source_without_lineno(handler: PythonHandler) -> None: + """Test rendering objects without a line number.""" + code = dedent( + """ + '''Module docstring.''' + + class Class: + '''Class docstring.''' + + def function(self): + '''Function docstring.''' + + attribute = 0 + '''Attribute docstring.''' + """, + ) + with temporary_visited_module(code) as module: + # TODO: Remove once Griffe does that automatically. + module.lines_collection[module.filepath] = code.splitlines() # type: ignore[index] + + module["Class"].lineno = None + module["Class.function"].lineno = None + module["attribute"].lineno = None + assert handler.render(module, {"show_source": True}) diff --git a/tests/test_rendering.py b/tests/test_rendering.py index 38d81dbb..1bab29d7 100644 --- a/tests/test_rendering.py +++ b/tests/test_rendering.py @@ -7,8 +7,7 @@ from typing import TYPE_CHECKING, Any import pytest -from griffe.collections import ModulesCollection -from griffe.tests import temporary_visited_module +from griffe import ModulesCollection, temporary_visited_module from mkdocstrings_handlers.python import rendering