From 73f11dcc584a672af7e17738cba08a50f119176a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sat, 19 Oct 2024 19:49:04 +0200 Subject: [PATCH 001/100] fix: Always render cross-references outside of signatures Issue-mkdocstrings#700: https://github.com/mkdocstrings/mkdocstrings/issues/700 --- .../material/_base/expression.html.jinja | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja index c34c0be5..4aea143d 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja @@ -32,15 +32,16 @@ which is a tree-like structure representing a Python expression. {%- set annotation = full -%} {%- endif -%} {%- for title, path in annotation|split_path(full) -%} - {%- if config.signature_crossrefs -%} - {%- if signature -%} - {%- filter stash_crossref(length=title|length) -%} - {{ title }} - {%- endfilter -%} - {%- else -%} + {%- if not signature -%} + {#- Always render cross-references outside of signatures. We don't need to stash them. -#} + {{ title }} + {%- elif config.signature_crossrefs -%} + {#- We're in a signature and cross-references are enabled, we must render one and stash it. -#} + {%- filter stash_crossref(length=title|length) -%} {{ title }} - {%- endif -%} + {%- endfilter -%} {%- else -%} + {#- We're in a signature but cross-references are disabled, we just render the title. -#} {{ title }} {%- endif -%} {%- if not loop.last -%}.{%- endif -%} From 1b064a0f21b32afb2686ac320d89ccde6d5fb294 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sat, 19 Oct 2024 19:54:17 +0200 Subject: [PATCH 002/100] chore: Prepare release 1.12.2 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d9f4c0d..8c03b29f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [1.12.2](https://github.com/mkdocstrings/python/releases/tag/1.12.2) - 2024-10-19 + +[Compare with 1.12.1](https://github.com/mkdocstrings/python/compare/1.12.1...1.12.2) + +### Bug Fixes + +- Always render cross-references outside of signatures ([73f11dc](https://github.com/mkdocstrings/python/commit/73f11dcc584a672af7e17738cba08a50f119176a) by Timothée Mazzucotelli). [Issue-mkdocstrings#700](https://github.com/mkdocstrings/mkdocstrings/issues/700) + ## [1.12.1](https://github.com/mkdocstrings/python/releases/tag/1.12.1) - 2024-10-14 [Compare with 1.12.0](https://github.com/mkdocstrings/python/compare/1.12.0...1.12.1) From c6dab06939ceb687bbab2fa5f6ce21d8ee3532f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 26 Nov 2024 14:57:23 +0100 Subject: [PATCH 003/100] perf: Compute all members of a class only once --- .../templates/material/_base/class.html.jinja | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index 24046e8f..da48545f 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -18,7 +18,7 @@ Context: {% endblock logs %}
- {% with obj = class, html_id = class.path %} + {% with obj = class, html_id = class.path, all_members = class.all_members %} {% if root %} {% set show_full_path = config.show_root_full_path %} @@ -49,8 +49,8 @@ Context: {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} {{ class_name }} - {% elif config.merge_init_into_class and "__init__" in class.all_members %} - {% with function = class.all_members["__init__"] %} + {% elif config.merge_init_into_class and "__init__" in all_members %} + {% with function = all_members["__init__"] %} {%+ filter highlight(language="python", inline=True) %} {{ class_name }}{% include "signature"|get_template with context %} {% endfilter %} @@ -78,8 +78,8 @@ Context: 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__"] %} + {% if "__init__" in all_members %} + {% with function = all_members["__init__"] %} {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} {{ class.name }} {% endfilter %} @@ -132,8 +132,8 @@ Context: {% include "docstring"|get_template with context %} {% endwith %} {% if config.merge_init_into_class %} - {% if "__init__" in class.all_members and class.all_members["__init__"].has_docstring %} - {% with function = class.all_members["__init__"] %} + {% if "__init__" in all_members and all_members["__init__"].has_docstring %} + {% with function = all_members["__init__"] %} {% with obj = function, docstring_sections = function.docstring.parsed %} {% include "docstring"|get_template with context %} {% endwith %} @@ -157,8 +157,8 @@ Context: -#} {% if config.show_source %} {% if config.merge_init_into_class %} - {% if "__init__" in class.all_members and class.all_members["__init__"].source %} - {% with init = class.all_members["__init__"] %} + {% if "__init__" in all_members and all_members["__init__"].source %} + {% with init = all_members["__init__"] %}
Source code in {%- if init.relative_filepath.is_absolute() -%} From 6c5b5c341940af9425b3de0672ac400794b3f6e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 26 Nov 2024 15:01:26 +0100 Subject: [PATCH 004/100] fix: Don't merge parent `__init__` docstring into class docstring if such inherited method wasn't selected through the `inherited_members` configuration option Issue-189: https://github.com/mkdocstrings/python/issues/189 --- .../templates/material/_base/class.html.jinja | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index da48545f..eac70beb 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -132,13 +132,17 @@ Context: {% include "docstring"|get_template with context %} {% endwith %} {% if config.merge_init_into_class %} - {% if "__init__" in all_members and all_members["__init__"].has_docstring %} - {% with function = all_members["__init__"] %} - {% with obj = function, docstring_sections = function.docstring.parsed %} - {% include "docstring"|get_template with context %} + {# We don't want to merge the inherited `__init__` method docstring into the class docstring #} + {# if such inherited method was not selected through `inherited_members`. #} + {% with check_members = all_members if (config.inherited_members is true or (config.inherited_members is iterable and "__init__" in config.inherited_members)) else class.members %} + {% if "__init__" in check_members and check_members["__init__"].has_docstring %} + {% with function = check_members["__init__"] %} + {% with obj = function, docstring_sections = function.docstring.parsed %} + {% include "docstring"|get_template with context %} + {% endwith %} {% endwith %} - {% endwith %} - {% endif %} + {% endif %} + {% endwith %} {% endif %} {% endblock docstring %} From 101a6dc428da59a512da617a0a2453f2b6ef4387 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 26 Nov 2024 15:18:52 +0100 Subject: [PATCH 005/100] fix: Fix normalization of extension paths on the annoying operating system and Python 3.13 Python 3.13 changed `os.path.isabs`: > On Windows, `isabs()` no longer considers paths starting with exactly one slash (`\` or `/`) to be absolute. See https://docs.python.org/3/whatsnew/3.13.html#os-path. --- src/mkdocstrings_handlers/python/handler.py | 8 +++----- tests/test_handler.py | 9 +++++---- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 0aac3cdc..628b56ec 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -469,11 +469,9 @@ def normalize_extension_paths(self, extensions: Sequence) -> Sequence: pth = str(ext) options = None - if pth.endswith(".py") or ".py:" in pth or "/" in pth or "\\" in pth: # noqa: SIM102 - # This is a sytem path. Normalize it. - if not os.path.isabs(pth): - # Make path absolute relative to config file path. - pth = os.path.normpath(os.path.join(base_path, pth)) + if pth.endswith(".py") or ".py:" in pth or "/" in pth or "\\" in pth: + # This is a system path. Normalize it, make it absolute relative to config file path. + pth = os.path.abspath(os.path.join(base_path, pth)) if options is not None: normalized.append({pth: options}) diff --git a/tests/test_handler.py b/tests/test_handler.py index 0717dc48..6c2381db 100644 --- a/tests/test_handler.py +++ b/tests/test_handler.py @@ -119,10 +119,11 @@ def test_expand_globs_without_changing_directory() -> None: (True, {"extension.py:SomeExtension": {"option": "value"}}), (True, {"path/to/extension.py": {"option": "value"}}), (True, {"path/to/extension.py:SomeExtension": {"option": "value"}}), - (False, "/absolute/path/to/extension.py"), - (False, "/absolute/path/to/extension.py:SomeExtension"), - (False, {"/absolute/path/to/extension.py": {"option": "value"}}), - (False, {"/absolute/path/to/extension.py:SomeExtension": {"option": "value"}}), + # True because OS path normalization. + (True, "/absolute/path/to/extension.py"), + (True, "/absolute/path/to/extension.py:SomeExtension"), + (True, {"/absolute/path/to/extension.py": {"option": "value"}}), + (True, {"/absolute/path/to/extension.py:SomeExtension": {"option": "value"}}), (False, "dot.notation.path.to.extension"), (False, "dot.notation.path.to.pyextension"), (False, {"dot.notation.path.to.extension": {"option": "value"}}), From 53eb82a21bbcaa959306e909bf0d4ac468f87580 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 26 Nov 2024 16:22:57 +0100 Subject: [PATCH 006/100] fix: Respect highlight's `linenums` config for `pycon` examples in docstrings The reasoning is that someone enabling line numbers globally supposedly also wants them for code blocks in docstrings. There's in my opinion no difference between a code block in a Markdown document and a code block in a docstring, they both serve documentation purposes and should be subject to the same rendering rules. If that makes someone unhappy, we can always consider adding an option to hide line numbers for code blocks in docstrings. Related-to-#192: https://github.com/mkdocstrings/python/issues/192 --- .../templates/material/_base/docstring/examples.html.jinja | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index dd0b503f..5a086497 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja @@ -23,6 +23,6 @@ Context: {% if section_type.value == "text" %} {{ sub_section|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} {% elif section_type.value == "examples" %} - {{ sub_section|highlight(language="pycon", linenums=False) }} + {{ sub_section|highlight(language="pycon") }} {% endif %} {% endfor %} From a669f1caefbd54305cc4610bdd57a529aa1208cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 26 Nov 2024 16:24:28 +0100 Subject: [PATCH 007/100] fix: Never render line numbers for signatures and attribute values Issue-192: https://github.com/mkdocstrings/python/issues/192 --- src/mkdocstrings_handlers/python/rendering.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py index a7ea38f7..b3667b03 100644 --- a/src/mkdocstrings_handlers/python/rendering.py +++ b/src/mkdocstrings_handlers/python/rendering.py @@ -169,6 +169,7 @@ def do_format_signature( language="python", inline=False, classes=["doc-signature"], + linenums=False, ), ) @@ -230,6 +231,7 @@ def do_format_attribute( language="python", inline=False, classes=["doc-signature"], + linenums=False, ), ) From 3bf55b22ce9a841242c55b2efcedbd8f3a99ccc9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 3 Dec 2024 16:22:06 +0100 Subject: [PATCH 008/100] fix: Actually check if a module is public when rendering auto-generated summary table for modules Issue-203: https://github.com/mkdocstrings/python/issues/203 --- src/mkdocstrings_handlers/python/rendering.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py index b3667b03..5cbd5ebf 100644 --- a/src/mkdocstrings_handlers/python/rendering.py +++ b/src/mkdocstrings_handlers/python/rendering.py @@ -594,7 +594,7 @@ def do_as_modules_section( description=module.docstring.value.split("\n", 1)[0] if module.docstring else "", ) for module in modules - if not check_public or module + if not check_public or module.is_public ], ) From af6fab31142204872ace716392dcb314b2cb5d0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 3 Dec 2024 16:36:26 +0100 Subject: [PATCH 009/100] fix: Handle `__init__` overloads when merging into class Issue-212: https://github.com/mkdocstrings/python/issues/212 --- .../templates/material/_base/class.html.jinja | 21 +++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index eac70beb..ff5e51c9 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -76,13 +76,26 @@ Context: {#- Signature block. This block renders the signature for the class. + Overloads of the `__init__` method are rendered if `merge_init_into_class` is enabled. + The actual `__init__` method signature is only rendered if `separate_signature` is also enabled. -#} - {% if config.separate_signature and config.merge_init_into_class %} + {% if config.merge_init_into_class %} {% if "__init__" in all_members %} {% with function = all_members["__init__"] %} - {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} - {{ class.name }} - {% endfilter %} + {% if function.overloads %} +
+ {% for overload in function.overloads %} + {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %} + {{ class.name }} + {% endfilter %} + {% endfor %} +
+ {% endif %} + {% if config.separate_signature %} + {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} + {{ class.name }} + {% endfilter %} + {% endif %} {% endwith %} {% endif %} {% endif %} From e93d166a14d0944d30ff2f28f21f2262ac396bff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 3 Dec 2024 17:14:37 +0100 Subject: [PATCH 010/100] fix: Respect `show_signature_annotations` option for attribute signatures in headings Issue-griffe-pydantic#9: https://github.com/mkdocstrings/griffe-pydantic/issues/9 --- .../python/templates/material/_base/attribute.html.jinja | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index 0716b171..7f3707b6 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja @@ -52,7 +52,7 @@ Context: {{ attribute_name }} {% else %} {%+ filter highlight(language="python", inline=True) %} - {{ attribute_name }}{% if attribute.annotation %}: {{ attribute.annotation }}{% endif %} + {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %} {% if attribute.value %} = {{ attribute.value }}{% endif %} {% endfilter %} {% endif %} From cea49964ac8364e2087f3016baa88168e67dec7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 3 Dec 2024 19:31:43 +0100 Subject: [PATCH 011/100] docs: Mention mkdocstrings-python-xref Issue-199: https://github.com/mkdocstrings/python/issues/199 --- docs/usage/configuration/docstrings.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md index d88cbbfb..0cf2dac1 100644 --- a/docs/usage/configuration/docstrings.md +++ b/docs/usage/configuration/docstrings.md @@ -427,6 +427,7 @@ class Class: /// +INFO: **There is an alternative, third-party Python handler that handles relative references: [mkdocstrings-python-xref](https://github.com/analog-garage/mkdocstrings-python-xref).** ## `scoped_crossrefs` From c4506f080e0c75cd32d6512c80f5016e82fc12bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 19 Dec 2024 17:51:29 +0100 Subject: [PATCH 012/100] refactor: Render `*` and `**` outside of cross-references in signatures Needed-for-PR-216: https://github.com/mkdocstrings/python/pull/216 --- .../templates/material/_base/signature.html.jinja | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja index 641b8b8d..750cac30 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja @@ -72,27 +72,27 @@ Context: {%- endif -%} {#- Prepare name. -#} - {%- set param_name -%} + {%- set param_prefix -%} {%- if parameter.kind.value == "variadic positional" -%} * {%- elif parameter.kind.value == "variadic keyword" -%} ** {%- endif -%} - {{ parameter.name }} {%- endset -%} {#- Render parameter name with optional cross-reference to its heading. -#} + {{ param_prefix }} {%- if config.separate_signature and config.parameter_headings and config.signature_crossrefs -%} - {%- filter stash_crossref(length=param_name|length) -%} + {%- filter stash_crossref(length=parameter.name|length) -%} {%- with func_path = function.path -%} {%- if config.merge_init_into_class and func_path.endswith(".__init__") -%} {%- set func_path = func_path[:-9] -%} {%- endif -%} - {{ param_name }} + {{ parameter.name }} {%- endwith -%} {%- endfilter -%} {%- else -%} - {{ param_name }} + {{ parameter.name }} {%- endif -%} {#- Render parameter annotation. -#} From d67215c976938ef1e169f16dd0b6166067ebd7bc Mon Sep 17 00:00:00 2001 From: dm Date: Thu, 19 Dec 2024 18:11:04 +0100 Subject: [PATCH 013/100] feat: Allow using Ruff to format signatures and attribute values PR-216: https://github.com/mkdocstrings/python/pull/216 --- docs/.glossary.md | 1 + docs/schema.json | 2 +- docs/usage/configuration/signatures.md | 18 +++-- src/mkdocstrings_handlers/python/handler.py | 2 +- src/mkdocstrings_handlers/python/rendering.py | 70 ++++++++++++++++--- tests/test_rendering.py | 18 +++-- 6 files changed, 89 insertions(+), 22 deletions(-) diff --git a/docs/.glossary.md b/docs/.glossary.md index 588674fb..917c95c4 100644 --- a/docs/.glossary.md +++ b/docs/.glossary.md @@ -8,5 +8,6 @@ [Spacy's documentation]: https://spacy.io/api/doc/ [Black]: https://pypi.org/project/black/ [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material +[Ruff]: https://docs.astral.sh/ruff *[ToC]: Table of Contents diff --git a/docs/schema.json b/docs/schema.json index b4eca004..e1863d26 100644 --- a/docs/schema.json +++ b/docs/schema.json @@ -145,7 +145,7 @@ "default": false }, "separate_signature": { - "title": "Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it.", + "title": "Whether to put the whole signature in a code block below the heading. If a formatter (Black or Ruff) is installed, the signature is also formatted using it.", "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#separate_signature", "type": "boolean", "default": false diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index e5e4cb88..879db6b1 100644 --- a/docs/usage/configuration/signatures.md +++ b/docs/usage/configuration/signatures.md @@ -154,10 +154,15 @@ def convert(text: str, md: Markdown) -> Markup: Maximum line length when formatting code/signatures. When separating signatures from headings with the [`separate_signature`][] option, -the Python handler will try to format the signatures using [Black] and +the Python handler will try to format the signatures using a formatter and the specified line length. -If Black is not installed, the handler issues an INFO log once. +The handler will automatically try to format using : + +1. [Black] +2. [Ruff] + +If a formatter is not found, the handler issues an INFO log once. ```yaml title="in mkdocs.yml (global configuration)" plugins: @@ -380,10 +385,15 @@ function(param1, param2=None) Whether to put the whole signature in a code block below the heading. When separating signatures from headings, -the Python handler will try to format the signatures using [Black] and +the Python handler will try to format the signatures using a formatter and the specified [line length][line_length]. -If Black is not installed, the handler issues an INFO log once. +The handler will automatically try to format using : + +1. [Black] +2. [Ruff] + +If a formatter is not found, the handler issues an INFO log once. ```yaml title="in mkdocs.yml (global configuration)" plugins: diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 628b56ec..4171fd76 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -201,7 +201,7 @@ class PythonHandler(BaseHandler): show_signature_annotations (bool): Show the type annotations in methods and functions signatures. Default: `False`. signature_crossrefs (bool): Whether to render cross-references for type annotations in signatures. Default: `False`. separate_signature (bool): Whether to put the whole signature in a code block below the heading. - If Black is installed, the signature is also formatted using it. Default: `False`. + If a formatter (Black or Ruff) is installed, the signature is also formatted using it. Default: `False`. unwrap_annotated (bool): Whether to unwrap `Annotated` types to show only the type without the annotations. Default: `False`. modernize_annotations (bool): Whether to modernize annotations, for example `Optional[str]` into `str | None`. Default: `False`. """ diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py index 5cbd5ebf..085f0c34 100644 --- a/src/mkdocstrings_handlers/python/rendering.py +++ b/src/mkdocstrings_handlers/python/rendering.py @@ -6,6 +6,7 @@ import random import re import string +import subprocess import sys import warnings from functools import lru_cache @@ -71,11 +72,11 @@ def _sort_key_source(item: CollectorItem) -> Any: def do_format_code(code: str, line_length: int) -> str: - """Format code using Black. + """Format code. Parameters: code: The code to format. - line_length: The line length to give to Black. + line_length: The line length. Returns: The same code, formatted. @@ -83,7 +84,7 @@ def do_format_code(code: str, line_length: int) -> str: code = code.strip() if len(code) < line_length: return code - formatter = _get_black_formatter() + formatter = _get_formatter() return formatter(code, line_length) @@ -118,7 +119,7 @@ def _format_signature(name: Markup, signature: str, line_length: int) -> str: # Black cannot format names with dots, so we replace # the whole name with a string of equal length name_length = len(name) - formatter = _get_black_formatter() + formatter = _get_formatter() formatable = f"def {'x' * name_length}{signature}: pass" formatted = formatter(formatable, line_length) @@ -137,13 +138,13 @@ def do_format_signature( annotations: bool | None = None, crossrefs: bool = False, # noqa: ARG001 ) -> str: - """Format a signature using Black. + """Format a signature. Parameters: context: Jinja context, passed automatically. callable_path: The path of the callable we render the signature of. function: The function we render the signature of. - line_length: The line length to give to Black. + line_length: The line length. annotations: Whether to show type annotations. crossrefs: Whether to cross-reference types in the signature. @@ -199,13 +200,13 @@ def do_format_attribute( *, crossrefs: bool = False, # noqa: ARG001 ) -> str: - """Format an attribute using Black. + """Format an attribute. Parameters: context: Jinja context, passed automatically. attribute_path: The path of the callable we render the signature of. attribute: The attribute we render the signature of. - line_length: The line length to give to Black. + line_length: The line length. crossrefs: Whether to cross-reference types in the signature. Returns: @@ -434,12 +435,59 @@ def do_filter_objects( @lru_cache(maxsize=1) -def _get_black_formatter() -> Callable[[str, int], str]: +def _get_formatter() -> Callable[[str, int], str]: + for formatter_function in [ + _get_black_formatter, + _get_ruff_formatter, + ]: + if (formatter := formatter_function()) is not None: + return formatter + + logger.info("Formatting signatures requires either Black or Ruff to be installed.") + return lambda text, _: text + + +def _get_ruff_formatter() -> Callable[[str, int], str] | None: + try: + from ruff.__main__ import find_ruff_bin + except ImportError: + return None + + try: + ruff_bin = find_ruff_bin() + except FileNotFoundError: + ruff_bin = "ruff" + + def formatter(code: str, line_length: int) -> str: + try: + completed_process = subprocess.run( # noqa: S603 + [ + ruff_bin, + "format", + "--config", + f"line-length={line_length}", + "--stdin-filename", + "file.py", + "-", + ], + check=True, + capture_output=True, + text=True, + input=code, + ) + except subprocess.CalledProcessError: + return code + else: + return completed_process.stdout + + return formatter + + +def _get_black_formatter() -> Callable[[str, int], str] | None: try: from black import InvalidInput, Mode, format_str except ModuleNotFoundError: - logger.info("Formatting signatures requires Black to be installed.") - return lambda text, _: text + return None def formatter(code: str, line_length: int) -> str: mode = Mode(line_length=line_length) diff --git a/tests/test_rendering.py b/tests/test_rendering.py index 1bab29d7..081702f4 100644 --- a/tests/test_rendering.py +++ b/tests/test_rendering.py @@ -4,7 +4,7 @@ import re from dataclasses import dataclass -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING, Any, Callable import pytest from griffe import ModulesCollection, temporary_visited_module @@ -22,14 +22,22 @@ "aaaaa(bbbbb, ccccc=1) + ddddd.eeeee[ffff] or {ggggg: hhhhh, iiiii: jjjjj}", ], ) -def test_format_code(code: str) -> None: - """Assert code can be Black-formatted. +@pytest.mark.parametrize( + "formatter", + [ + rendering._get_black_formatter(), + rendering._get_ruff_formatter(), + rendering._get_formatter(), + ], +) +def test_format_code(code: str, formatter: Callable[[str, int], str]) -> None: + """Assert code can be formatted. Parameters: code: Code to format. """ for length in (5, 100): - assert rendering.do_format_code(code, length) + assert formatter(code, length) @pytest.mark.parametrize( @@ -37,7 +45,7 @@ def test_format_code(code: str) -> None: [("Class.method", "(param: str = 'hello') -> 'OtherClass'")], ) def test_format_signature(name: Markup, signature: str) -> None: - """Assert signatures can be Black-formatted. + """Assert signatures can be formatted. Parameters: signature: Signature to format. From ec4d2cc392a33f42033fe0ea44dc9eef55e335c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 23 Dec 2024 15:23:07 +0100 Subject: [PATCH 014/100] chore: Template upgrade --- .copier-answers.yml | 2 +- .github/workflows/ci.yml | 9 +- .github/workflows/release.yml | 5 +- README.md | 1 - docs/insiders/index.md | 2 + pyproject.toml | 14 ++- scripts/gen_credits.py | 2 +- scripts/make | 191 +--------------------------------- scripts/make.py | 191 ++++++++++++++++++++++++++++++++++ 9 files changed, 216 insertions(+), 201 deletions(-) mode change 100755 => 120000 scripts/make create mode 100755 scripts/make.py diff --git a/.copier-answers.yml b/.copier-answers.yml index 1dc4ac4d..225aa5e8 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier -_commit: 1.2.0 +_commit: 1.2.2 _src_path: gh:mkdocstrings/handler-template author_email: dev@pawamoy.fr author_fullname: Timothée Mazzucotelli diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6940069d..594d1c42 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,9 +25,9 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - - - name: Fetch all tags - run: git fetch --depth=1 --tags + with: + fetch-depth: 0 + fetch-tags: true - name: Setup Python uses: actions/setup-python@v5 @@ -106,6 +106,9 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + with: + fetch-depth: 0 + fetch-tags: true - name: Setup Python uses: actions/setup-python@v5 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 45bcf5a4..9388125b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -11,8 +11,9 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 - - name: Fetch all tags - run: git fetch --depth=1 --tags + with: + fetch-depth: 0 + fetch-tags: true - name: Setup Python uses: actions/setup-python@v5 with: diff --git a/README.md b/README.md index a65bf00c..937a3a84 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,6 @@ [![ci](https://github.com/mkdocstrings/python/workflows/ci/badge.svg)](https://github.com/mkdocstrings/python/actions?query=workflow%3Aci) [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://mkdocstrings.github.io/python/) [![pypi version](https://img.shields.io/pypi/v/mkdocstrings-python.svg)](https://pypi.org/project/mkdocstrings-python/) -[![gitpod](https://img.shields.io/badge/gitpod-workspace-708FCC.svg?style=flat)](https://gitpod.io/#https://github.com/mkdocstrings/python) [![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#python:gitter.im) --- diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 3bc3aa56..17a11ce4 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -92,6 +92,8 @@ else: ``` +Additionally, your sponsorship will give more weight to your upvotes on issues, helping us prioritize work items in our backlog. For more information on how we prioritize work, see this page: [Backlog management](https://pawamoy.github.io/backlog/). + ## How to become a sponsor Thanks for your interest in sponsoring! In order to become an eligible sponsor diff --git a/pyproject.toml b/pyproject.toml index 636a67fe..a30c8aa9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,6 +52,8 @@ version = {source = "scm"} package-dir = "src" includes = ["src/mkdocstrings_handlers"] editable-backend = "editables" + +# Include as much as possible in the source distribution, to help redistributors. excludes = ["**/.pytest_cache"] source-includes = [ "config", @@ -66,15 +68,21 @@ source-includes = [ ] [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 = "."}, ] [tool.uv] -dev-dependencies = [ - # dev - "editables>=0.5", +# Tell uv to ignore constraints on the main package. +# This is needed when the current project doesn't have Git tags (fork, CI). +override-dependencies = ["mkdocstrings-python"] +sources = { mkdocstrings-python = { workspace = true } } +[dependency-groups] +dev = [ # maintenance "build>=1.2", "git-changelog>=2.5", diff --git a/scripts/gen_credits.py b/scripts/gen_credits.py index 51ebe2f3..85240535 100644 --- a/scripts/gen_credits.py +++ b/scripts/gen_credits.py @@ -27,7 +27,7 @@ pyproject = tomllib.load(pyproject_file) project = pyproject["project"] project_name = project["name"] -devdeps = [dep for dep in pyproject["tool"]["uv"]["dev-dependencies"] if not dep.startswith("-e")] +devdeps = [dep for dep in pyproject["dependency-groups"]["dev"] if not dep.startswith("-e")] PackageMetadata = dict[str, Union[str, Iterable[str]]] Metadata = dict[str, PackageMetadata] diff --git a/scripts/make b/scripts/make deleted file mode 100755 index ac430624..00000000 --- a/scripts/make +++ /dev/null @@ -1,190 +0,0 @@ -#!/usr/bin/env python3 -"""Management commands.""" - -from __future__ import annotations - -import os -import shutil -import subprocess -import sys -from contextlib import contextmanager -from pathlib import Path -from textwrap import dedent -from typing import Any, Iterator - -PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.9 3.10 3.11 3.12 3.13 3.14").split() - - -def shell(cmd: str, capture_output: bool = False, **kwargs: Any) -> str | None: - """Run a shell command.""" - if capture_output: - return subprocess.check_output(cmd, shell=True, text=True, **kwargs) # noqa: S602 - subprocess.run(cmd, shell=True, check=True, stderr=subprocess.STDOUT, **kwargs) # noqa: S602 - return None - - -@contextmanager -def environ(**kwargs: str) -> Iterator[None]: - """Temporarily set environment variables.""" - original = dict(os.environ) - os.environ.update(kwargs) - try: - yield - finally: - os.environ.clear() - os.environ.update(original) - - -def uv_install(venv: Path) -> None: - """Install dependencies using uv.""" - with environ(UV_PROJECT_ENVIRONMENT=str(venv), PYO3_USE_ABI3_FORWARD_COMPATIBILITY="1"): - if "CI" in os.environ: - shell("uv sync --no-editable") - else: - shell("uv sync") - - -def setup() -> None: - """Setup the project.""" - if not shutil.which("uv"): - raise ValueError("make: setup: uv must be installed, see https://github.com/astral-sh/uv") - - print("Installing dependencies (default environment)") # noqa: T201 - default_venv = Path(".venv") - if not default_venv.exists(): - shell("uv venv --python python") - uv_install(default_venv) - - if PYTHON_VERSIONS: - for version in PYTHON_VERSIONS: - print(f"\nInstalling dependencies (python{version})") # noqa: T201 - venv_path = Path(f".venvs/{version}") - if not venv_path.exists(): - shell(f"uv venv --python {version} {venv_path}") - with environ(UV_PROJECT_ENVIRONMENT=str(venv_path.resolve())): - uv_install(venv_path) - - -def run(version: str, cmd: str, *args: str, no_sync: bool = False, **kwargs: Any) -> None: - """Run a command in a virtual environment.""" - kwargs = {"check": True, **kwargs} - uv_run = ["uv", "run"] - if no_sync: - uv_run.append("--no-sync") - if version == "default": - with environ(UV_PROJECT_ENVIRONMENT=".venv"): - subprocess.run([*uv_run, cmd, *args], **kwargs) # noqa: S603, PLW1510 - else: - with environ(UV_PROJECT_ENVIRONMENT=f".venvs/{version}", MULTIRUN="1"): - subprocess.run([*uv_run, cmd, *args], **kwargs) # noqa: S603, PLW1510 - - -def multirun(cmd: str, *args: str, **kwargs: Any) -> None: - """Run a command for all configured Python versions.""" - if PYTHON_VERSIONS: - for version in PYTHON_VERSIONS: - run(version, cmd, *args, **kwargs) - else: - run("default", cmd, *args, **kwargs) - - -def allrun(cmd: str, *args: str, **kwargs: Any) -> None: - """Run a command in all virtual environments.""" - run("default", cmd, *args, **kwargs) - if PYTHON_VERSIONS: - multirun(cmd, *args, **kwargs) - - -def clean() -> None: - """Delete build artifacts and cache files.""" - paths_to_clean = ["build", "dist", "htmlcov", "site", ".coverage*", ".pdm-build"] - for path in paths_to_clean: - shell(f"rm -rf {path}") - - cache_dirs = {".cache", ".pytest_cache", ".mypy_cache", ".ruff_cache", "__pycache__"} - for dirpath in Path(".").rglob("*/"): - if dirpath.parts[0] not in (".venv", ".venvs") and dirpath.name in cache_dirs: - shutil.rmtree(dirpath, ignore_errors=True) - - -def vscode() -> None: - """Configure VSCode to work on this project.""" - Path(".vscode").mkdir(parents=True, exist_ok=True) - shell("cp -v config/vscode/* .vscode") - - -def main() -> int: - """Main entry point.""" - args = list(sys.argv[1:]) - if not args or args[0] == "help": - if len(args) > 1: - run("default", "duty", "--help", args[1]) - else: - print( - dedent( - """ - Available commands - help Print this help. Add task name to print help. - setup Setup all virtual environments (install dependencies). - run Run a command in the default virtual environment. - multirun Run a command for all configured Python versions. - allrun Run a command in all virtual environments. - 3.x Run a command in the virtual environment for Python 3.x. - clean Delete build artifacts and cache files. - vscode Configure VSCode to work on this project. - """ - ), - flush=True, - ) # noqa: T201 - if os.path.exists(".venv"): - print("\nAvailable tasks", flush=True) # noqa: T201 - run("default", "duty", "--list", no_sync=True) - return 0 - - while args: - cmd = args.pop(0) - - if cmd == "run": - run("default", *args) - return 0 - - if cmd == "multirun": - multirun(*args) - return 0 - - if cmd == "allrun": - allrun(*args) - return 0 - - if cmd.startswith("3."): - run(cmd, *args) - return 0 - - opts = [] - while args and (args[0].startswith("-") or "=" in args[0]): - opts.append(args.pop(0)) - - if cmd == "clean": - clean() - elif cmd == "setup": - setup() - elif cmd == "vscode": - vscode() - elif cmd == "check": - multirun("duty", "check-quality", "check-types", "check-docs") - run("default", "duty", "check-api") - elif cmd in {"check-quality", "check-docs", "check-types", "test"}: - multirun("duty", cmd, *opts) - else: - run("default", "duty", cmd, *opts) - - return 0 - - -if __name__ == "__main__": - try: - sys.exit(main()) - except subprocess.CalledProcessError as process: - if process.output: - print(process.output, file=sys.stderr) # noqa: T201 - sys.exit(process.returncode) diff --git a/scripts/make b/scripts/make new file mode 120000 index 00000000..c2eda0df --- /dev/null +++ b/scripts/make @@ -0,0 +1 @@ +make.py \ No newline at end of file diff --git a/scripts/make.py b/scripts/make.py new file mode 100755 index 00000000..3d427296 --- /dev/null +++ b/scripts/make.py @@ -0,0 +1,191 @@ +#!/usr/bin/env python3 +"""Management commands.""" + +from __future__ import annotations + +import os +import shutil +import subprocess +import sys +from contextlib import contextmanager +from pathlib import Path +from textwrap import dedent +from typing import TYPE_CHECKING, Any + +if TYPE_CHECKING: + from collections.abc import Iterator + + +PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.9 3.10 3.11 3.12 3.13 3.14").split() + + +def shell(cmd: str, *, capture_output: bool = False, **kwargs: Any) -> str | None: + """Run a shell command.""" + if capture_output: + return subprocess.check_output(cmd, shell=True, text=True, **kwargs) # noqa: S602 + subprocess.run(cmd, shell=True, check=True, stderr=subprocess.STDOUT, **kwargs) # noqa: S602 + return None + + +@contextmanager +def environ(**kwargs: str) -> Iterator[None]: + """Temporarily set environment variables.""" + original = dict(os.environ) + os.environ.update(kwargs) + try: + yield + finally: + os.environ.clear() + os.environ.update(original) + + +def uv_install(venv: Path) -> None: + """Install dependencies using uv.""" + with environ(UV_PROJECT_ENVIRONMENT=str(venv), PYO3_USE_ABI3_FORWARD_COMPATIBILITY="1"): + if "CI" in os.environ: + shell("uv sync --no-editable") + else: + shell("uv sync") + + +def setup() -> None: + """Setup the project.""" + if not shutil.which("uv"): + raise ValueError("make: setup: uv must be installed, see https://github.com/astral-sh/uv") + + print("Installing dependencies (default environment)") + default_venv = Path(".venv") + if not default_venv.exists(): + shell("uv venv") + uv_install(default_venv) + + if PYTHON_VERSIONS: + for version in PYTHON_VERSIONS: + print(f"\nInstalling dependencies (python{version})") + venv_path = Path(f".venvs/{version}") + if not venv_path.exists(): + shell(f"uv venv --python {version} {venv_path}") + with environ(UV_PROJECT_ENVIRONMENT=str(venv_path.resolve())): + uv_install(venv_path) + + +def run(version: str, cmd: str, *args: str, **kwargs: Any) -> None: + """Run a command in a virtual environment.""" + kwargs = {"check": True, **kwargs} + uv_run = ["uv", "run", "--no-sync"] + if version == "default": + with environ(UV_PROJECT_ENVIRONMENT=".venv"): + subprocess.run([*uv_run, cmd, *args], **kwargs) # noqa: S603, PLW1510 + else: + with environ(UV_PROJECT_ENVIRONMENT=f".venvs/{version}", MULTIRUN="1"): + subprocess.run([*uv_run, cmd, *args], **kwargs) # noqa: S603, PLW1510 + + +def multirun(cmd: str, *args: str, **kwargs: Any) -> None: + """Run a command for all configured Python versions.""" + if PYTHON_VERSIONS: + for version in PYTHON_VERSIONS: + run(version, cmd, *args, **kwargs) + else: + run("default", cmd, *args, **kwargs) + + +def allrun(cmd: str, *args: str, **kwargs: Any) -> None: + """Run a command in all virtual environments.""" + run("default", cmd, *args, **kwargs) + if PYTHON_VERSIONS: + multirun(cmd, *args, **kwargs) + + +def clean() -> None: + """Delete build artifacts and cache files.""" + paths_to_clean = ["build", "dist", "htmlcov", "site", ".coverage*", ".pdm-build"] + for path in paths_to_clean: + shutil.rmtree(path, ignore_errors=True) + + cache_dirs = {".cache", ".pytest_cache", ".mypy_cache", ".ruff_cache", "__pycache__"} + for dirpath in Path(".").rglob("*/"): + if dirpath.parts[0] not in (".venv", ".venvs") and dirpath.name in cache_dirs: + shutil.rmtree(dirpath, ignore_errors=True) + + +def vscode() -> None: + """Configure VSCode to work on this project.""" + shutil.copytree("config/vscode", ".vscode", dirs_exist_ok=True) + + +def main() -> int: + """Main entry point.""" + args = list(sys.argv[1:]) + if not args or args[0] == "help": + if len(args) > 1: + run("default", "duty", "--help", args[1]) + else: + print( + dedent( + """ + Available commands + help Print this help. Add task name to print help. + setup Setup all virtual environments (install dependencies). + run Run a command in the default virtual environment. + multirun Run a command for all configured Python versions. + allrun Run a command in all virtual environments. + 3.x Run a command in the virtual environment for Python 3.x. + clean Delete build artifacts and cache files. + vscode Configure VSCode to work on this project. + """, + ), + flush=True, + ) + if os.path.exists(".venv"): + print("\nAvailable tasks", flush=True) + run("default", "duty", "--list") + return 0 + + while args: + cmd = args.pop(0) + + if cmd == "run": + run("default", *args) + return 0 + + if cmd == "multirun": + multirun(*args) + return 0 + + if cmd == "allrun": + allrun(*args) + return 0 + + if cmd.startswith("3."): + run(cmd, *args) + return 0 + + opts = [] + while args and (args[0].startswith("-") or "=" in args[0]): + opts.append(args.pop(0)) + + if cmd == "clean": + clean() + elif cmd == "setup": + setup() + elif cmd == "vscode": + vscode() + elif cmd == "check": + multirun("duty", "check-quality", "check-types", "check-docs") + run("default", "duty", "check-api") + elif cmd in {"check-quality", "check-docs", "check-types", "test"}: + multirun("duty", cmd, *opts) + else: + run("default", "duty", cmd, *opts) + + return 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except subprocess.CalledProcessError as process: + if process.output: + print(process.output, file=sys.stderr) + sys.exit(process.returncode) From 0d953e384fac3f4439933daa0bd7022c7baea5a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 24 Dec 2024 15:42:07 +0100 Subject: [PATCH 015/100] chore: Template upgrade --- .copier-answers.yml | 2 +- pyproject.toml | 11 +++-------- scripts/get_version.py | 27 +++++++++++++++++++++++++++ 3 files changed, 31 insertions(+), 9 deletions(-) create mode 100644 scripts/get_version.py diff --git a/.copier-answers.yml b/.copier-answers.yml index 225aa5e8..a7f91ade 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier -_commit: 1.2.2 +_commit: 1.2.3 _src_path: gh:mkdocstrings/handler-template author_email: dev@pawamoy.fr author_fullname: Timothée Mazzucotelli diff --git a/pyproject.toml b/pyproject.toml index a30c8aa9..4c6e3ef4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,8 +45,9 @@ Discussions = "https://github.com/mkdocstrings/python/discussions" Gitter = "https://gitter.im/mkdocstrings/python" Funding = "https://github.com/sponsors/pawamoy" -[tool.pdm] -version = {source = "scm"} +[tool.pdm.version] +source = "call" +getter = "scripts.get_version:get_version" [tool.pdm.build] package-dir = "src" @@ -75,12 +76,6 @@ data = [ {path = "share/**/*", relative-to = "."}, ] -[tool.uv] -# Tell uv to ignore constraints on the main package. -# This is needed when the current project doesn't have Git tags (fork, CI). -override-dependencies = ["mkdocstrings-python"] -sources = { mkdocstrings-python = { workspace = true } } - [dependency-groups] dev = [ # maintenance diff --git a/scripts/get_version.py b/scripts/get_version.py new file mode 100644 index 00000000..f4a30a8c --- /dev/null +++ b/scripts/get_version.py @@ -0,0 +1,27 @@ +"""Get current project version from Git tags or changelog.""" + +import re +from contextlib import suppress +from pathlib import Path + +from pdm.backend.hooks.version import SCMVersion, Version, default_version_formatter, get_version_from_scm + +_root = Path(__file__).parent.parent +_changelog = _root / "CHANGELOG.md" +_changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$") +_default_scm_version = SCMVersion(Version("0.0.0"), None, False, None, None) # noqa: FBT003 + + +def get_version() -> str: + """Get current project version from Git tags or changelog.""" + scm_version = get_version_from_scm(_root) or _default_scm_version + if scm_version.version <= Version("0.1"): # Missing Git tags? + with suppress(OSError, StopIteration): # noqa: SIM117 + with _changelog.open("r", encoding="utf8") as file: + match = next(filter(None, map(_changelog_version_re.match, file))) + scm_version = scm_version._replace(version=Version(match.group(1))) + return default_version_formatter(scm_version) + + +if __name__ == "__main__": + print(get_version()) From e4936638b9d80ed1bc918e545f65b0b46b9a91d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 23 Dec 2024 13:46:17 +0100 Subject: [PATCH 016/100] tests: Refactor fixtures and helpers --- tests/conftest.py | 114 +++++++++++++++++++++++++++++-------------- tests/helpers.py | 94 +++++++++++++++++++++++++++++++++++ tests/test_themes.py | 10 ++-- 3 files changed, 174 insertions(+), 44 deletions(-) create mode 100644 tests/helpers.py diff --git a/tests/conftest.py b/tests/conftest.py index 88105e4c..1c53cba4 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -2,25 +2,29 @@ from __future__ import annotations -from collections import ChainMap -from typing import TYPE_CHECKING, Any +from collections.abc import Iterator +from typing import TYPE_CHECKING import pytest -from markdown.core import Markdown -from mkdocs.config.defaults import MkDocsConfig + +from tests import helpers if TYPE_CHECKING: from collections.abc import Iterator from pathlib import Path - from mkdocs import config + from markdown.core import Markdown + from mkdocs.config.defaults import MkDocsConfig from mkdocstrings.plugin import MkdocstringsPlugin from mkdocstrings_handlers.python.handler import PythonHandler +# -------------------------------------------- +# Function-scoped fixtures. +# -------------------------------------------- @pytest.fixture(name="mkdocs_conf") -def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[config.Config]: +def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[MkDocsConfig]: """Yield a MkDocs configuration object. Parameters: @@ -30,34 +34,12 @@ def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Itera Yields: MkDocs config. """ - conf = MkDocsConfig() - while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"): - request = request._parent_request - - conf_dict = { - "site_name": "foo", - "site_url": "https://example.org/", - "site_dir": str(tmp_path), - "plugins": [{"mkdocstrings": {"default_handler": "python"}}], - **getattr(request, "param", {}), - } - # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289 - mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", []))) - - conf.load_dict(conf_dict) - assert conf.validate() == ([], []) - - conf["mdx_configs"] = mdx_configs - conf["markdown_extensions"].insert(0, "toc") # Guaranteed to be added by MkDocs. - - conf = conf["plugins"]["mkdocstrings"].on_config(conf) - conf = conf["plugins"]["autorefs"].on_config(conf) - yield conf - conf["plugins"]["mkdocstrings"].on_post_build(conf) + with helpers.mkdocs_conf(request, tmp_path) as mkdocs_conf: + yield mkdocs_conf @pytest.fixture(name="plugin") -def fixture_plugin(mkdocs_conf: config.Config) -> MkdocstringsPlugin: +def fixture_plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin: """Return a plugin instance. Parameters: @@ -66,11 +48,11 @@ def fixture_plugin(mkdocs_conf: config.Config) -> MkdocstringsPlugin: Returns: mkdocstrings plugin instance. """ - return mkdocs_conf["plugins"]["mkdocstrings"] + return helpers.plugin(mkdocs_conf) @pytest.fixture(name="ext_markdown") -def fixture_ext_markdown(mkdocs_conf: config.Config) -> Markdown: +def fixture_ext_markdown(mkdocs_conf: MkDocsConfig) -> Markdown: """Return a Markdown instance with MkdocstringsExtension. Parameters: @@ -79,7 +61,7 @@ def fixture_ext_markdown(mkdocs_conf: config.Config) -> Markdown: Returns: A Markdown instance. """ - return Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"]) + return helpers.ext_markdown(mkdocs_conf) @pytest.fixture(name="handler") @@ -92,6 +74,64 @@ def fixture_handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> Pytho Returns: A handler instance. """ - handler = plugin.handlers.get_handler("python") - handler._update_env(ext_markdown, plugin.handlers._config) - return handler # type: ignore[return-value] + return helpers.handler(plugin, ext_markdown) + + +# -------------------------------------------- +# Session-scoped fixtures. +# -------------------------------------------- +@pytest.fixture(name="session_mkdocs_conf", scope="session") +def fixture_session_mkdocs_conf( + request: pytest.FixtureRequest, + tmp_path_factory: pytest.TempPathFactory, +) -> Iterator[MkDocsConfig]: + """Yield a MkDocs configuration object. + + Parameters: + request: Pytest fixture. + tmp_path: Pytest fixture. + + Yields: + MkDocs config. + """ + with helpers.mkdocs_conf(request, tmp_path_factory.mktemp("project")) as mkdocs_conf: + yield mkdocs_conf + + +@pytest.fixture(name="session_plugin", scope="session") +def fixture_session_plugin(session_mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin: + """Return a plugin instance. + + Parameters: + mkdocs_conf: Pytest fixture (see conftest.py). + + Returns: + mkdocstrings plugin instance. + """ + return helpers.plugin(session_mkdocs_conf) + + +@pytest.fixture(name="session_ext_markdown", scope="session") +def fixture_session_ext_markdown(session_mkdocs_conf: MkDocsConfig) -> Markdown: + """Return a Markdown instance with MkdocstringsExtension. + + Parameters: + mkdocs_conf: Pytest fixture (see conftest.py). + + Returns: + A Markdown instance. + """ + return helpers.ext_markdown(session_mkdocs_conf) + + +@pytest.fixture(name="session_handler", scope="session") +def fixture_session_handler(session_plugin: MkdocstringsPlugin, session_ext_markdown: Markdown) -> PythonHandler: + """Return a handler instance. + + Parameters: + plugin: Pytest fixture (see conftest.py). + + Returns: + A handler instance. + """ + return helpers.handler(session_plugin, session_ext_markdown) diff --git a/tests/helpers.py b/tests/helpers.py new file mode 100644 index 00000000..91ea4eee --- /dev/null +++ b/tests/helpers.py @@ -0,0 +1,94 @@ +"""Configuration for the pytest test suite.""" + +from __future__ import annotations + +from collections import ChainMap +from contextlib import contextmanager +from typing import TYPE_CHECKING, Any + +from markdown.core import Markdown +from mkdocs.config.defaults import MkDocsConfig + +if TYPE_CHECKING: + from collections.abc import Iterator + from pathlib import Path + + import pytest + from mkdocstrings.plugin import MkdocstringsPlugin + + from mkdocstrings_handlers.python.handler import PythonHandler + + +@contextmanager +def mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[MkDocsConfig]: + """Yield a MkDocs configuration object. + + Parameters: + request: Pytest request fixture. + tmp_path: Temporary path. + + Yields: + MkDocs config. + """ + conf = MkDocsConfig() + while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"): + request = request._parent_request + + conf_dict = { + "site_name": "foo", + "site_url": "https://example.org/", + "site_dir": str(tmp_path), + "plugins": [{"mkdocstrings": {"default_handler": "python"}}], + **getattr(request, "param", {}), + } + # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289 + mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", []))) + + conf.load_dict(conf_dict) + assert conf.validate() == ([], []) + + conf["mdx_configs"] = mdx_configs + conf["markdown_extensions"].insert(0, "toc") # Guaranteed to be added by MkDocs. + + conf = conf["plugins"]["mkdocstrings"].on_config(conf) + conf = conf["plugins"]["autorefs"].on_config(conf) + yield conf + conf["plugins"]["mkdocstrings"].on_post_build(conf) + + +def plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin: + """Return a plugin instance. + + Parameters: + mkdocs_conf: MkDocs configuration. + + Returns: + mkdocstrings plugin instance. + """ + return mkdocs_conf["plugins"]["mkdocstrings"] + + +def ext_markdown(mkdocs_conf: MkDocsConfig) -> Markdown: + """Return a Markdown instance with MkdocstringsExtension. + + Parameters: + mkdocs_conf: MkDocs configuration. + + Returns: + A Markdown instance. + """ + return Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"]) + + +def handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> PythonHandler: + """Return a handler instance. + + Parameters: + plugin: Plugin instance. + + Returns: + A handler instance. + """ + handler = plugin.handlers.get_handler("python") + handler._update_env(ext_markdown, plugin.handlers._config) + return handler # type: ignore[return-value] diff --git a/tests/test_themes.py b/tests/test_themes.py index a4ad0d59..035f453e 100644 --- a/tests/test_themes.py +++ b/tests/test_themes.py @@ -7,8 +7,7 @@ import pytest if TYPE_CHECKING: - from markdown import Markdown - from mkdocstrings.plugin import MkdocstringsPlugin + from mkdocstrings.handlers.python import PythonHandler @pytest.mark.parametrize( @@ -32,15 +31,12 @@ "mkdocstrings_handlers.python", ], ) -def test_render_themes_templates_python(identifier: str, plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> None: +def test_render_themes_templates_python(identifier: str, handler: PythonHandler) -> None: """Test rendering of a given theme's templates. Parameters: identifier: Parametrized identifier. - plugin: Pytest fixture (see conftest.py). - ext_markdown: Pytest fixture (see conftest.py). + handler: Python handler (fixture). """ - handler = plugin.handlers.get_handler("python") - handler._update_env(ext_markdown, plugin.handlers._config) data = handler.collect(identifier, {}) handler.render(data, {}) From c8f1a77dc5150e0dec0f43649c2b04e422028f37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 23 Dec 2024 13:48:10 +0100 Subject: [PATCH 017/100] tests: Add templates rendenring tests using inline-snapshot Issue-150: https://github.com/mkdocstrings/python/issues/150 --- duties.py | 10 +- pyproject.toml | 7 +- tests/snapshots/__init__.py | 405 ++++++++++++++ tests/snapshots/external/.gitignore | 2 + ...dd5e8edcfae4bdc1d8cb7f2ff76cd1c46cce5.html | 132 +++++ ...9122c48eca0a19d0611df530e607f5bacdf6f.html | 132 +++++ ...8e06269c51be673389f29fa8b2d90cff54eb2.html | 55 ++ ...3dd3bee62fb9b1c8b2a39991550e7845c2b02.html | 506 +++++++++++++++++ ...9e1eff4cd66196506a37977cdb33325a50718.html | 355 ++++++++++++ ...fcbd0259b652d0534259efea7815aa15b1122.html | 320 +++++++++++ ...136f18a94eedec6bc5a036dcecc005e70dc80.html | 22 + ...8df96539455d9cad42b09b248ab65b5c742e2.html | 55 ++ ...72ddf797f6a90dfd5a3e649e6e4c127b86562.html | 57 ++ ...ca42ec5a8f62db8d650231b0748ddce8c85f1.html | 59 ++ ...b57e5babd34165edccf619b62a06fc1936cd5.html | 24 + ...b197c530710fe8c150c4dd3fbbfb7d38928cc.html | 55 ++ ...ffa96645eb2af29983e75d807fccff96d8f75.html | 318 +++++++++++ ...2de5c360e49fb403078a82ec408d829afcb72.html | 22 + ...1ec60dfefb8871c69ceb1d7a035bd3bdadab8.html | 55 ++ ...978c1c1d3ef56a572031a307fe1cad1f17eff.html | 324 +++++++++++ ...d1354d39b74380402b255ee60741e97c9960c.html | 22 + ...61112dc8098f90e71f71d5aceba8be188fcf7.html | 26 + ...9c80414c8441a962f6466afdb280dc022af26.html | 97 ++++ ...c83195b1c6eea319d1a0679b2baa797d9859c.html | 22 + ...7bf76d169fc80b3d3e465213671b7f6e548eb.html | 132 +++++ ...76cccaa968163b35641d705f288c04fe4937e.html | 24 + ...d8b3570f0dac7e132efb1bf0cdbf77e9e2c59.html | 24 + ...78753a06f359527ea4adac85c72a7812b21d3.html | 318 +++++++++++ ...39da701df9a7ce8006dc7781c148d27a89756.html | 57 ++ ...66ec4245e286bf75b989cf50979ce187e1a16.html | 22 + ...032a9c23ffe82913060e3b66f29bf81a6a585.html | 55 ++ ...800830fd980daabff9df8c3760eb6edea7915.html | 136 +++++ ...a3cdf3b2b9ceeb839044c72c63b469914f0a1.html | 57 ++ ...5eff78f5783b14d3c88e71c6477eaa8493113.html | 24 + ...ae2d95ba8685e16d2c79749f675b5b2a6cea5.html | 289 ++++++++++ ...9a630e4d2c7ad95308bc5c7a56a8a8930b37f.html | 190 +++++++ ...6a3b6727936de92f73f299ba238491f619937.html | 24 + ...3bc24f601f89cab70eae1b2af5ee21cfb1f3a.html | 24 + ...69973b715cceacdadefc540109aad3c274bde.html | 508 ++++++++++++++++++ ...7d8ba0bbb22330cb08eaec2e84159bde4159b.html | 353 ++++++++++++ ...947e4fcaf2c5a6c68cad6355d8611c1cc2e3f.html | 318 +++++++++++ ...0e8cd6a1a0223055f08b80031452eb05d9484.html | 318 +++++++++++ ...f4d99a53ed21894c51517b3d79da445b0a705.html | 59 ++ ...bd59a1aee444bfa0cd3b9cfb6d052d378a041.html | 57 ++ ...a46c9ea93c80bc49e1a1de100349341d93fb9.html | 97 ++++ ...058052d9748874cdd911feacdd31d1abe5d97.html | 24 + ...5dddda972f16623f7710f738ffe2bcf9130d9.html | 57 ++ ...e0b452db5a1ffd88e52479db2b52a170fd8f9.html | 506 +++++++++++++++++ ...90ab3e808e3a67f3c15a9f9e3e143d7956e49.html | 22 + ...ad4ed6582d10df2449c7d92f1e43a91610666.html | 97 ++++ ...bb6225798eaf25be6fd4171bd73b7354509b6.html | 55 ++ ...2bb0bd08bf23dc054c6f7938a04f42feab99d.html | 167 ++++++ ...d446cf9da94eee8db306f08bae1ca0db0ca1d.html | 24 + ...9ea7be278d7890c46cf28ecc3cfd35a36fb46.html | 55 ++ ...c1760f5eb69d7db6401da2f28518d0e8065c4.html | 318 +++++++++++ ...f8e0921b074015ae19680abf5df995c233ba1.html | 24 + ...68fde16c32d92bed42fb3193f98e0e3f04602.html | 353 ++++++++++++ ...3a1ad12398888fdad84bfbda3de8b19072611.html | 57 ++ ...4e80480ab25f8885aa83b97776e6b0cc6b570.html | 136 +++++ ...85ffda5caf1f1479851275bc227857fb01400.html | 22 + ...c69a33e7dd44500e9337718cd96da1bb56325.html | 320 +++++++++++ ...5f1bd537e661588b1742d93d0a6543cc3592c.html | 477 ++++++++++++++++ ...087f430f62d787c32225ac8b4039c92e20b76.html | 55 ++ ...dcf6610f1c2c971c9c46b5665d276716b8821.html | 24 + ...d652dee02c47b1339f858fc1d7a54aae9ed46.html | 26 + ...c726e65fcd85804942be0c67b4f05f452a549.html | 22 + ...c766ad95e05197d30d881540fbe52cdc07ff8.html | 55 ++ ...0eb7ef0264a783a3c47d1114d21fa8cfa3947.html | 506 +++++++++++++++++ ...0f8d65379375a6bd390da30f5676bf2289cf2.html | 289 ++++++++++ ...8626f2d5fd8eed9a3ba81abebd76f8afc6861.html | 22 + ...0006fc3acd857f068e78e6d1c2461bbd4063f.html | 57 ++ ...fb45bef54a847517e5d90e130818c2a06b163.html | 190 +++++++ ...529a61c6cec71b18da2e4f02206ec18b901ef.html | 353 ++++++++++++ ...482aee444228e86e23357c11881498e711bb2.html | 24 + ...ee528d3abc2fbd04413d1c11916a243d7567a.html | 24 + ...b541fde66297f257d9baf1b0f94b3ea49e6e0.html | 24 + ...8db0ff3fcd73530442a30c48cf01dcbc30aaa.html | 318 +++++++++++ ...d3036e707a177b2ba2bdad25a6998bec570b7.html | 506 +++++++++++++++++ ...ef718bb3ae2092760b707e838fb73164b3720.html | 57 ++ ...d55f5d2e7c62dd245fed4b3f002a5e9a4d646.html | 24 + ...97ebe4d43669929ec1cdedba4d418899aecc7.html | 26 + ...5b791b6521504f19a8d7496592dee59c7f199.html | 24 + ...caaf7a210c0a31e71de950e791c5eb33a6258.html | 97 ++++ ...0307076be3cf83b0a9ec2fb5c949324b7e172.html | 57 ++ ...8cc3a2ec894372644a8eaee597418e9b55b3c.html | 318 +++++++++++ ...8ba497874115be6c5e9431838b4bb6931b2f4.html | 22 + ...4aa243a093ccd362a63e33dbd6202ae8ab75d.html | 353 ++++++++++++ ...3706797feb3042ac88c8fcf0a6da277eddb9d.html | 26 + ...5317b8c3d00d1108d28d7ef2949994b41dcbd.html | 24 + ...a75bec4276e61254539632a1d5f8f2c6c3452.html | 318 +++++++++++ ...0404967562a2ffd1700ca35c9788949ca55c0.html | 22 + ...ea3edf681a937f647b11925e9932006648a11.html | 22 + tests/test_end_to_end.py | 168 ++++++ 93 files changed, 12932 insertions(+), 3 deletions(-) create mode 100644 tests/snapshots/__init__.py create mode 100644 tests/snapshots/external/.gitignore create mode 100644 tests/snapshots/external/052c34f22e4c711b1f13f53085cdd5e8edcfae4bdc1d8cb7f2ff76cd1c46cce5.html create mode 100644 tests/snapshots/external/052e71e7e9d5bec710fb2d36b009122c48eca0a19d0611df530e607f5bacdf6f.html create mode 100644 tests/snapshots/external/09d96d69d9dcbc54c8189fb885e8e06269c51be673389f29fa8b2d90cff54eb2.html create mode 100644 tests/snapshots/external/0b1372d7f7c057905f665ad506f3dd3bee62fb9b1c8b2a39991550e7845c2b02.html create mode 100644 tests/snapshots/external/0c2924ff976fa0e32ba66558a4f9e1eff4cd66196506a37977cdb33325a50718.html create mode 100644 tests/snapshots/external/0fac4f5e7f455b351c60268567bfcbd0259b652d0534259efea7815aa15b1122.html create mode 100644 tests/snapshots/external/11598fec2d07bb675dfa8a57e49136f18a94eedec6bc5a036dcecc005e70dc80.html create mode 100644 tests/snapshots/external/166b8dfab738b90f2ff0df84a048df96539455d9cad42b09b248ab65b5c742e2.html create mode 100644 tests/snapshots/external/247a6063b698c285bfef7addfd972ddf797f6a90dfd5a3e649e6e4c127b86562.html create mode 100644 tests/snapshots/external/26bc66c2ba29feddfbd06c2490eca42ec5a8f62db8d650231b0748ddce8c85f1.html create mode 100644 tests/snapshots/external/28d8862dd086c7d523516dd4091b57e5babd34165edccf619b62a06fc1936cd5.html create mode 100644 tests/snapshots/external/2bf34b4dd82e753b21200ec980cb197c530710fe8c150c4dd3fbbfb7d38928cc.html create mode 100644 tests/snapshots/external/347d4ffe2cb3f2ca3f0d1f3f09cffa96645eb2af29983e75d807fccff96d8f75.html create mode 100644 tests/snapshots/external/366b0537fe0625a10d55203a3532de5c360e49fb403078a82ec408d829afcb72.html create mode 100644 tests/snapshots/external/388a13d71284b1a4b0c457e9c8d1ec60dfefb8871c69ceb1d7a035bd3bdadab8.html create mode 100644 tests/snapshots/external/3d072a22b9513eecb51c6a5f39b978c1c1d3ef56a572031a307fe1cad1f17eff.html create mode 100644 tests/snapshots/external/3f5d794823a451ec9d4ed8c7e16d1354d39b74380402b255ee60741e97c9960c.html create mode 100644 tests/snapshots/external/42c053a5e567a777dfde62cd0d061112dc8098f90e71f71d5aceba8be188fcf7.html create mode 100644 tests/snapshots/external/4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html create mode 100644 tests/snapshots/external/44e42f27bfe3d3b5ec14700c247c83195b1c6eea319d1a0679b2baa797d9859c.html create mode 100644 tests/snapshots/external/46e56f39b10d1e8ee4017bc11457bf76d169fc80b3d3e465213671b7f6e548eb.html create mode 100644 tests/snapshots/external/4892e0fe1920c0bb22fa4787b6e76cccaa968163b35641d705f288c04fe4937e.html create mode 100644 tests/snapshots/external/4f60da13e2d45e803f73ed41746d8b3570f0dac7e132efb1bf0cdbf77e9e2c59.html create mode 100644 tests/snapshots/external/59a9e1ffb2f0807b594a933444c78753a06f359527ea4adac85c72a7812b21d3.html create mode 100644 tests/snapshots/external/5a9c10410801aa75b33878971b939da701df9a7ce8006dc7781c148d27a89756.html create mode 100644 tests/snapshots/external/5cf0130e3b4fdd536b1c99ee66c66ec4245e286bf75b989cf50979ce187e1a16.html create mode 100644 tests/snapshots/external/62e18d3e57777d911c7fdee1fcc032a9c23ffe82913060e3b66f29bf81a6a585.html create mode 100644 tests/snapshots/external/6a02b544c12c68b75d9bf3b85b1800830fd980daabff9df8c3760eb6edea7915.html create mode 100644 tests/snapshots/external/6d12192d6b4dc0633bad697a683a3cdf3b2b9ceeb839044c72c63b469914f0a1.html create mode 100644 tests/snapshots/external/7107066872137b807b3f9d897e75eff78f5783b14d3c88e71c6477eaa8493113.html create mode 100644 tests/snapshots/external/728c1344630190ac84514ebd8e5ae2d95ba8685e16d2c79749f675b5b2a6cea5.html create mode 100644 tests/snapshots/external/735fc6ffdb82ce35cdab2aed2389a630e4d2c7ad95308bc5c7a56a8a8930b37f.html create mode 100644 tests/snapshots/external/74bfab19cbd4ba02673f6b9ee736a3b6727936de92f73f299ba238491f619937.html create mode 100644 tests/snapshots/external/76ee8e01e1c0b94de84d79da8443bc24f601f89cab70eae1b2af5ee21cfb1f3a.html create mode 100644 tests/snapshots/external/7c988c9e13efeadd20b911a95cc69973b715cceacdadefc540109aad3c274bde.html create mode 100644 tests/snapshots/external/7d5fe66539191786245991395e77d8ba0bbb22330cb08eaec2e84159bde4159b.html create mode 100644 tests/snapshots/external/83119803338105f101311992d31947e4fcaf2c5a6c68cad6355d8611c1cc2e3f.html create mode 100644 tests/snapshots/external/88855b0284174733b57edd2043e0e8cd6a1a0223055f08b80031452eb05d9484.html create mode 100644 tests/snapshots/external/8b097c69ac2fd52857f33e1b008f4d99a53ed21894c51517b3d79da445b0a705.html create mode 100644 tests/snapshots/external/8d4e1f9af9971bd21234c7c45dfbd59a1aee444bfa0cd3b9cfb6d052d378a041.html create mode 100644 tests/snapshots/external/955e5111f4262f280b0787a22dfa46c9ea93c80bc49e1a1de100349341d93fb9.html create mode 100644 tests/snapshots/external/95f8e480937f7a2b956392ed4d8058052d9748874cdd911feacdd31d1abe5d97.html create mode 100644 tests/snapshots/external/96cf94f4822a5cf5d72407eab5a5dddda972f16623f7710f738ffe2bcf9130d9.html create mode 100644 tests/snapshots/external/981438492e387bc82b23f09e3c5e0b452db5a1ffd88e52479db2b52a170fd8f9.html create mode 100644 tests/snapshots/external/9bd282a6f2fe82f3ffe66b175bf90ab3e808e3a67f3c15a9f9e3e143d7956e49.html create mode 100644 tests/snapshots/external/9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html create mode 100644 tests/snapshots/external/9d03089a46fab9a86b0836444cabb6225798eaf25be6fd4171bd73b7354509b6.html create mode 100644 tests/snapshots/external/a1167b14f5a71a283817bf5866d2bb0bd08bf23dc054c6f7938a04f42feab99d.html create mode 100644 tests/snapshots/external/a185e216dc7b7ebb31b46ea0e7ed446cf9da94eee8db306f08bae1ca0db0ca1d.html create mode 100644 tests/snapshots/external/a200913d9a7d51c52ab58f6fc4e9ea7be278d7890c46cf28ecc3cfd35a36fb46.html create mode 100644 tests/snapshots/external/a2c5be9bd5d1f0db3ff64b44353c1760f5eb69d7db6401da2f28518d0e8065c4.html create mode 100644 tests/snapshots/external/ab0ddac637b536c06014746a4a8f8e0921b074015ae19680abf5df995c233ba1.html create mode 100644 tests/snapshots/external/ae74b5980f9b6996ed6e112d53168fde16c32d92bed42fb3193f98e0e3f04602.html create mode 100644 tests/snapshots/external/afd5c166367dd47e4f9843d906b3a1ad12398888fdad84bfbda3de8b19072611.html create mode 100644 tests/snapshots/external/b060b701543e5503dc848538a164e80480ab25f8885aa83b97776e6b0cc6b570.html create mode 100644 tests/snapshots/external/b0a9b08f1f721721c4dd110cb8f85ffda5caf1f1479851275bc227857fb01400.html create mode 100644 tests/snapshots/external/b4b490164ab1a724cac7aba25bbc69a33e7dd44500e9337718cd96da1bb56325.html create mode 100644 tests/snapshots/external/ba51e100acd4f6ad91f1ef484aa5f1bd537e661588b1742d93d0a6543cc3592c.html create mode 100644 tests/snapshots/external/bd6594ae3b516bf84cd0b0e6605087f430f62d787c32225ac8b4039c92e20b76.html create mode 100644 tests/snapshots/external/c260e7f4ef3b8b228bb25879d3adcf6610f1c2c971c9c46b5665d276716b8821.html create mode 100644 tests/snapshots/external/c6e7ef9564cdc8449a98c0ef790d652dee02c47b1339f858fc1d7a54aae9ed46.html create mode 100644 tests/snapshots/external/c915eb92fd5dcc4e2c9da41ca72c726e65fcd85804942be0c67b4f05f452a549.html create mode 100644 tests/snapshots/external/c9a15552eed32a233795c2086a7c766ad95e05197d30d881540fbe52cdc07ff8.html create mode 100644 tests/snapshots/external/cc19537fdba4a26b10c60d5586b0eb7ef0264a783a3c47d1114d21fa8cfa3947.html create mode 100644 tests/snapshots/external/cdc8126d78b690d11c09e3128df0f8d65379375a6bd390da30f5676bf2289cf2.html create mode 100644 tests/snapshots/external/ce06da7f07b34e4f9071c5c001a8626f2d5fd8eed9a3ba81abebd76f8afc6861.html create mode 100644 tests/snapshots/external/cfcd41685591bcc497f9d1e9fd20006fc3acd857f068e78e6d1c2461bbd4063f.html create mode 100644 tests/snapshots/external/d1216ebf8e30ec559861678318efb45bef54a847517e5d90e130818c2a06b163.html create mode 100644 tests/snapshots/external/d540895f6bf91c8c8e4abc02f40529a61c6cec71b18da2e4f02206ec18b901ef.html create mode 100644 tests/snapshots/external/d5a6bf59c663338bef9fdc2391f482aee444228e86e23357c11881498e711bb2.html create mode 100644 tests/snapshots/external/d726cb8367d95b67ce78e718e88ee528d3abc2fbd04413d1c11916a243d7567a.html create mode 100644 tests/snapshots/external/e3defc3620e5fee20f9400c33b7b541fde66297f257d9baf1b0f94b3ea49e6e0.html create mode 100644 tests/snapshots/external/e6a9b76f268cde81a129e7273038db0ff3fcd73530442a30c48cf01dcbc30aaa.html create mode 100644 tests/snapshots/external/e8be7a9b1410e40dac79fe0ee29d3036e707a177b2ba2bdad25a6998bec570b7.html create mode 100644 tests/snapshots/external/e90c3e0c85ddaa068f3d063c6a1ef718bb3ae2092760b707e838fb73164b3720.html create mode 100644 tests/snapshots/external/eee65d3705a655eec6512c4aa09d55f5d2e7c62dd245fed4b3f002a5e9a4d646.html create mode 100644 tests/snapshots/external/f0014d9505eceb38ba1e36c380a97ebe4d43669929ec1cdedba4d418899aecc7.html create mode 100644 tests/snapshots/external/f3f3acb6b51ba98f5a06e7c62e85b791b6521504f19a8d7496592dee59c7f199.html create mode 100644 tests/snapshots/external/f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html create mode 100644 tests/snapshots/external/f6e292b8358a04e3471ba11c8820307076be3cf83b0a9ec2fb5c949324b7e172.html create mode 100644 tests/snapshots/external/f7711b8af7689b331209f8c034c8cc3a2ec894372644a8eaee597418e9b55b3c.html create mode 100644 tests/snapshots/external/f77f1c850398f972a7ae2229f918ba497874115be6c5e9431838b4bb6931b2f4.html create mode 100644 tests/snapshots/external/f848d4a9e516beeb1b1719630e34aa243a093ccd362a63e33dbd6202ae8ab75d.html create mode 100644 tests/snapshots/external/f8f32ea6a0c80a63854f8c8d78b3706797feb3042ac88c8fcf0a6da277eddb9d.html create mode 100644 tests/snapshots/external/fb5ebb7546d8d63744d7e6713ab5317b8c3d00d1108d28d7ef2949994b41dcbd.html create mode 100644 tests/snapshots/external/fb65efbbfc3ef9c2a06e6f539f8a75bec4276e61254539632a1d5f8f2c6c3452.html create mode 100644 tests/snapshots/external/fb770e6537bc1b98c0de03db7810404967562a2ffd1700ca35c9788949ca55c0.html create mode 100644 tests/snapshots/external/fba0d78ae23e4f52b5e6f0fe003ea3edf681a937f647b11925e9932006648a11.html create mode 100644 tests/test_end_to_end.py diff --git a/duties.py b/duties.py index 3864e74e..bd051334 100644 --- a/duties.py +++ b/duties.py @@ -217,20 +217,26 @@ def coverage(ctx: Context) -> None: @duty -def test(ctx: Context, *cli_args: str, match: str = "") -> None: +def test(ctx: Context, *cli_args: str, match: str = "", snapshot: str = "report") -> None: """Run the test suite. Parameters: match: A pytest expression to filter selected tests. + snapshot: Whether to "create", "fix", "trim", or "update" snapshots. """ py_version = f"{sys.version_info.major}{sys.version_info.minor}" os.environ["COVERAGE_FILE"] = f".coverage.{py_version}" + args = list(cli_args) + if snapshot == "disable" or not snapshot: + args = ["-n", "auto", "--inline-snapshot=disable"] + else: + args = [f"--inline-snapshot={snapshot}"] ctx.run( tools.pytest( "tests", config_file="config/pytest.ini", select=match, color="yes", - ).add_args("-n", "auto", *cli_args), + ).add_args(*args), title=pyprefix("Running tests"), ) diff --git a/pyproject.toml b/pyproject.toml index 4c6e3ef4..c6f3cc50 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -90,6 +90,8 @@ dev = [ "pytest-cov>=5.0", "pytest-randomly>=3.15", "pytest-xdist>=3.6", + "beautifulsoup4>=4.12.3", + "inline-snapshot>=0.18", "mypy>=1.10", "types-markdown>=3.6", "types-pyyaml>=6.0", @@ -107,4 +109,7 @@ dev = [ "mkdocs-minify-plugin>=0.8", # YORE: EOL 3.10: Remove line. "tomli>=2.0; python_version < '3.11'", -] \ No newline at end of file +] + +[tool.inline-snapshot] +storage-dir = "tests/snapshots" diff --git a/tests/snapshots/__init__.py b/tests/snapshots/__init__.py new file mode 100644 index 00000000..4469afed --- /dev/null +++ b/tests/snapshots/__init__.py @@ -0,0 +1,405 @@ +"""Snaphots for the inline-snapshot pytest plugin.""" + +from inline_snapshot import external, snapshot + +snapshots_signatures = snapshot( + { + ( + ("separate_signature", True), + ("show_signature_annotations", False), + ("signature_crossrefs", False), + ): external("4370d843cc76*.html"), + ( + ("separate_signature", True), + ("show_signature_annotations", True), + ("signature_crossrefs", True), + ): external("955e5111f426*.html"), + ( + ("separate_signature", False), + ("show_signature_annotations", True), + ("signature_crossrefs", True), + ): external("735fc6ffdb82*.html"), + ( + ("separate_signature", False), + ("show_signature_annotations", False), + ("signature_crossrefs", True), + ): external("6a02b544c12c*.html"), + ( + ("separate_signature", False), + ("show_signature_annotations", False), + ("signature_crossrefs", False), + ): external("b060b701543e*.html"), + ( + ("separate_signature", True), + ("show_signature_annotations", True), + ("signature_crossrefs", False), + ): external("f5ce06acbb7a*.html"), + ( + ("separate_signature", True), + ("show_signature_annotations", False), + ("signature_crossrefs", True), + ): external("9c0bfc0ee407*.html"), + ( + ("separate_signature", False), + ("show_signature_annotations", True), + ("signature_crossrefs", False), + ): external("d1216ebf8e30*.html"), + }, +) + +snapshots_members = snapshot( + { + ( + ("filters", ()), + ("inherited_members", ("method1",)), + ("members", False), + ): external("ab0ddac637b5*.html"), + (("filters", None), ("inherited_members", True), ("members", True)): external( + "0b1372d7f7c0*.html", + ), + (("filters", ()), ("inherited_members", False), ("members", True)): external( + "59a9e1ffb2f0*.html", + ), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ()), + ("members", ("module_attribute",)), + ): external("6d12192d6b4d*.html"), + (("filters", ()), ("inherited_members", ()), ("members", False)): external( + "366b0537fe06*.html", + ), + ( + ("filters", ()), + ("inherited_members", ("method1",)), + ("members", ("module_attribute",)), + ): external("e90c3e0c85dd*.html"), + (("filters", ()), ("inherited_members", True), ("members", True)): external( + "e8be7a9b1410*.html", + ), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ("method1",)), + ("members", ()), + ): external("f8f32ea6a0c8*.html"), + ( + ("filters", ()), + ("inherited_members", ("method1",)), + ("members", True), + ): external("d540895f6bf9*.html"), + (("filters", ()), ("inherited_members", False), ("members", False)): external( + "5cf0130e3b4f*.html", + ), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", True), + ("members", True), + ): external("7c988c9e13ef*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", False), + ("members", ()), + ): external("fb5ebb7546d8*.html"), + ( + ("filters", None), + ("inherited_members", ("method1",)), + ("members", ("module_attribute",)), + ): external("afd5c166367d*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ("method1",)), + ("members", ("module_attribute",)), + ): external("26bc66c2ba29*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", False), + ("members", ("module_attribute",)), + ): external("247a6063b698*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", False), + ("members", ("module_attribute",)), + ): external("5a9c10410801*.html"), + (("filters", ()), ("inherited_members", False), ("members", ())): external( + "fba0d78ae23e*.html", + ), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ("method1",)), + ("members", None), + ): external("cfcd41685591*.html"), + (("filters", ()), ("inherited_members", False), ("members", None)): external( + "a2c5be9bd5d1*.html", + ), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ()), + ("members", False), + ): external("76ee8e01e1c0*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ("method1",)), + ("members", ()), + ): external("42c053a5e567*.html"), + ( + ("filters", None), + ("inherited_members", ("method1",)), + ("members", ()), + ): external("4f60da13e2d4*.html"), + (("filters", ()), ("inherited_members", True), ("members", ())): external( + "c915eb92fd5d*.html", + ), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ()), + ("members", None), + ): external("c9a15552eed3*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ("method1",)), + ("members", None), + ): external("3d072a22b951*.html"), + (("filters", None), ("inherited_members", False), ("members", False)): external( + "9bd282a6f2fe*.html", + ), + ( + ("filters", None), + ("inherited_members", ()), + ("members", ("module_attribute",)), + ): external("166b8dfab738*.html"), + (("filters", None), ("inherited_members", ()), ("members", False)): external( + "44e42f27bfe3*.html", + ), + (("filters", None), ("inherited_members", False), ("members", None)): external( + "f7711b8af768*.html", + ), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", True), + ("members", ()), + ): external("28d8862dd086*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", True), + ("members", False), + ): external("f3f3acb6b51b*.html"), + (("filters", None), ("inherited_members", ()), ("members", True)): external( + "347d4ffe2cb3*.html", + ), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", True), + ("members", None), + ): external("ba51e100acd4*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", False), + ("members", False), + ): external("eee65d3705a6*.html"), + ( + ("filters", None), + ("inherited_members", False), + ("members", ("module_attribute",)), + ): external("a200913d9a7d*.html"), + ( + ("filters", None), + ("inherited_members", True), + ("members", ("module_attribute",)), + ): external("bd6594ae3b51*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", True), + ("members", ("module_attribute",)), + ): external("8d4e1f9af997*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", False), + ("members", ()), + ): external("d5a6bf59c663*.html"), + (("filters", None), ("inherited_members", ()), ("members", None)): external( + "88855b028417*.html", + ), + (("filters", ()), ("inherited_members", True), ("members", None)): external( + "981438492e38*.html", + ), + ( + ("filters", ()), + ("inherited_members", False), + ("members", ("module_attribute",)), + ): external("09d96d69d9dc*.html"), + ( + ("filters", None), + ("inherited_members", ("method1",)), + ("members", None), + ): external("ae74b5980f9b*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", True), + ("members", ()), + ): external("95f8e480937f*.html"), + (("filters", None), ("inherited_members", False), ("members", True)): external( + "831198033381*.html", + ), + ( + ("filters", ("module_attribute",)), + ("inherited_members", True), + ("members", True), + ): external("052c34f22e4c*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", False), + ("members", None), + ): external("cdc8126d78b6*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ("method1",)), + ("members", False), + ): external("f0014d9505ec*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", True), + ("members", ("module_attribute",)), + ): external("96cf94f4822a*.html"), + (("filters", None), ("inherited_members", True), ("members", ())): external( + "ce06da7f07b3*.html", + ), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ()), + ("members", False), + ): external("74bfab19cbd4*.html"), + ( + ("filters", None), + ("inherited_members", ("method1",)), + ("members", True), + ): external("7d5fe6653919*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", True), + ("members", False), + ): external("d726cb8367d9*.html"), + (("filters", None), ("inherited_members", False), ("members", ())): external( + "fb770e6537bc*.html", + ), + ( + ("filters", ("module_attribute",)), + ("inherited_members", True), + ("members", None), + ): external("2bf34b4dd82e*.html"), + ( + ("filters", ()), + ("inherited_members", ("method1",)), + ("members", ()), + ): external("4892e0fe1920*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ()), + ("members", True), + ): external("46e56f39b10d*.html"), + ( + ("filters", ()), + ("inherited_members", ()), + ("members", ("module_attribute",)), + ): external("388a13d71284*.html"), + (("filters", None), ("inherited_members", True), ("members", False)): external( + "3f5d794823a4*.html", + ), + ( + ("filters", ()), + ("inherited_members", True), + ("members", ("module_attribute",)), + ): external("9d03089a46fa*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ("method1",)), + ("members", ("module_attribute",)), + ): external("8b097c69ac2f*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", False), + ("members", True), + ): external("052e71e7e9d5*.html"), + ( + ("filters", None), + ("inherited_members", ("method1",)), + ("members", False), + ): external("e3defc3620e5*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ()), + ("members", True), + ): external("b4b490164ab1*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ("method1",)), + ("members", False), + ): external("c6e7ef9564cd*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", False), + ("members", None), + ): external("62e18d3e5777*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ()), + ("members", None), + ): external("728c13446301*.html"), + (("filters", None), ("inherited_members", ()), ("members", ())): external( + "f77f1c850398*.html", + ), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", False), + ("members", True), + ): external("0fac4f5e7f45*.html"), + (("filters", None), ("inherited_members", True), ("members", None)): external( + "cc19537fdba4*.html", + ), + (("filters", ()), ("inherited_members", ()), ("members", None)): external( + "e6a9b76f268c*.html", + ), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ()), + ("members", ()), + ): external("c260e7f4ef3b*.html"), + ( + ("filters", ("!module_attribute",)), + ("inherited_members", ("method1",)), + ("members", True), + ): external("0c2924ff976f*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ()), + ("members", ("module_attribute",)), + ): external("f6e292b8358a*.html"), + (("filters", ()), ("inherited_members", True), ("members", False)): external( + "b0a9b08f1f72*.html", + ), + (("filters", ()), ("inherited_members", ()), ("members", True)): external( + "fb65efbbfc3e*.html", + ), + ( + ("filters", ("module_attribute",)), + ("inherited_members", False), + ("members", False), + ): external("710706687213*.html"), + (("filters", ()), ("inherited_members", ()), ("members", ())): external( + "11598fec2d07*.html", + ), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ("method1",)), + ("members", True), + ): external("a1167b14f5a7*.html"), + ( + ("filters", ()), + ("inherited_members", ("method1",)), + ("members", None), + ): external("f848d4a9e516*.html"), + ( + ("filters", ("module_attribute",)), + ("inherited_members", ()), + ("members", ()), + ): external("a185e216dc7b*.html"), + }, +) diff --git a/tests/snapshots/external/.gitignore b/tests/snapshots/external/.gitignore new file mode 100644 index 00000000..45bef68b --- /dev/null +++ b/tests/snapshots/external/.gitignore @@ -0,0 +1,2 @@ +# ignore all snapshots which are not refered in the source +*-new.* diff --git a/tests/snapshots/external/052c34f22e4c711b1f13f53085cdd5e8edcfae4bdc1d8cb7f2ff76cd1c46cce5.html b/tests/snapshots/external/052c34f22e4c711b1f13f53085cdd5e8edcfae4bdc1d8cb7f2ff76cd1c46cce5.html new file mode 100644 index 00000000..e1a7d15c --- /dev/null +++ b/tests/snapshots/external/052c34f22e4c711b1f13f53085cdd5e8edcfae4bdc1d8cb7f2ff76cd1c46cce5.html @@ -0,0 +1,132 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/052e71e7e9d5bec710fb2d36b009122c48eca0a19d0611df530e607f5bacdf6f.html b/tests/snapshots/external/052e71e7e9d5bec710fb2d36b009122c48eca0a19d0611df530e607f5bacdf6f.html new file mode 100644 index 00000000..6866b45f --- /dev/null +++ b/tests/snapshots/external/052e71e7e9d5bec710fb2d36b009122c48eca0a19d0611df530e607f5bacdf6f.html @@ -0,0 +1,132 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/09d96d69d9dcbc54c8189fb885e8e06269c51be673389f29fa8b2d90cff54eb2.html b/tests/snapshots/external/09d96d69d9dcbc54c8189fb885e8e06269c51be673389f29fa8b2d90cff54eb2.html new file mode 100644 index 00000000..f2597daf --- /dev/null +++ b/tests/snapshots/external/09d96d69d9dcbc54c8189fb885e8e06269c51be673389f29fa8b2d90cff54eb2.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/0b1372d7f7c057905f665ad506f3dd3bee62fb9b1c8b2a39991550e7845c2b02.html b/tests/snapshots/external/0b1372d7f7c057905f665ad506f3dd3bee62fb9b1c8b2a39991550e7845c2b02.html new file mode 100644 index 00000000..89a3ea1e --- /dev/null +++ b/tests/snapshots/external/0b1372d7f7c057905f665ad506f3dd3bee62fb9b1c8b2a39991550e7845c2b02.html @@ -0,0 +1,506 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/0c2924ff976fa0e32ba66558a4f9e1eff4cd66196506a37977cdb33325a50718.html b/tests/snapshots/external/0c2924ff976fa0e32ba66558a4f9e1eff4cd66196506a37977cdb33325a50718.html new file mode 100644 index 00000000..5fb3da58 --- /dev/null +++ b/tests/snapshots/external/0c2924ff976fa0e32ba66558a4f9e1eff4cd66196506a37977cdb33325a50718.html @@ -0,0 +1,355 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/0fac4f5e7f455b351c60268567bfcbd0259b652d0534259efea7815aa15b1122.html b/tests/snapshots/external/0fac4f5e7f455b351c60268567bfcbd0259b652d0534259efea7815aa15b1122.html new file mode 100644 index 00000000..47cfb56f --- /dev/null +++ b/tests/snapshots/external/0fac4f5e7f455b351c60268567bfcbd0259b652d0534259efea7815aa15b1122.html @@ -0,0 +1,320 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/11598fec2d07bb675dfa8a57e49136f18a94eedec6bc5a036dcecc005e70dc80.html b/tests/snapshots/external/11598fec2d07bb675dfa8a57e49136f18a94eedec6bc5a036dcecc005e70dc80.html new file mode 100644 index 00000000..46cd4aee --- /dev/null +++ b/tests/snapshots/external/11598fec2d07bb675dfa8a57e49136f18a94eedec6bc5a036dcecc005e70dc80.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/166b8dfab738b90f2ff0df84a048df96539455d9cad42b09b248ab65b5c742e2.html b/tests/snapshots/external/166b8dfab738b90f2ff0df84a048df96539455d9cad42b09b248ab65b5c742e2.html new file mode 100644 index 00000000..b194ddc9 --- /dev/null +++ b/tests/snapshots/external/166b8dfab738b90f2ff0df84a048df96539455d9cad42b09b248ab65b5c742e2.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/247a6063b698c285bfef7addfd972ddf797f6a90dfd5a3e649e6e4c127b86562.html b/tests/snapshots/external/247a6063b698c285bfef7addfd972ddf797f6a90dfd5a3e649e6e4c127b86562.html new file mode 100644 index 00000000..c27a4c82 --- /dev/null +++ b/tests/snapshots/external/247a6063b698c285bfef7addfd972ddf797f6a90dfd5a3e649e6e4c127b86562.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/26bc66c2ba29feddfbd06c2490eca42ec5a8f62db8d650231b0748ddce8c85f1.html b/tests/snapshots/external/26bc66c2ba29feddfbd06c2490eca42ec5a8f62db8d650231b0748ddce8c85f1.html new file mode 100644 index 00000000..271501b7 --- /dev/null +++ b/tests/snapshots/external/26bc66c2ba29feddfbd06c2490eca42ec5a8f62db8d650231b0748ddce8c85f1.html @@ -0,0 +1,59 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/28d8862dd086c7d523516dd4091b57e5babd34165edccf619b62a06fc1936cd5.html b/tests/snapshots/external/28d8862dd086c7d523516dd4091b57e5babd34165edccf619b62a06fc1936cd5.html new file mode 100644 index 00000000..06640b9d --- /dev/null +++ b/tests/snapshots/external/28d8862dd086c7d523516dd4091b57e5babd34165edccf619b62a06fc1936cd5.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/2bf34b4dd82e753b21200ec980cb197c530710fe8c150c4dd3fbbfb7d38928cc.html b/tests/snapshots/external/2bf34b4dd82e753b21200ec980cb197c530710fe8c150c4dd3fbbfb7d38928cc.html new file mode 100644 index 00000000..eddcbb25 --- /dev/null +++ b/tests/snapshots/external/2bf34b4dd82e753b21200ec980cb197c530710fe8c150c4dd3fbbfb7d38928cc.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/347d4ffe2cb3f2ca3f0d1f3f09cffa96645eb2af29983e75d807fccff96d8f75.html b/tests/snapshots/external/347d4ffe2cb3f2ca3f0d1f3f09cffa96645eb2af29983e75d807fccff96d8f75.html new file mode 100644 index 00000000..9cd4b2fe --- /dev/null +++ b/tests/snapshots/external/347d4ffe2cb3f2ca3f0d1f3f09cffa96645eb2af29983e75d807fccff96d8f75.html @@ -0,0 +1,318 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/366b0537fe0625a10d55203a3532de5c360e49fb403078a82ec408d829afcb72.html b/tests/snapshots/external/366b0537fe0625a10d55203a3532de5c360e49fb403078a82ec408d829afcb72.html new file mode 100644 index 00000000..b6a621d2 --- /dev/null +++ b/tests/snapshots/external/366b0537fe0625a10d55203a3532de5c360e49fb403078a82ec408d829afcb72.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/388a13d71284b1a4b0c457e9c8d1ec60dfefb8871c69ceb1d7a035bd3bdadab8.html b/tests/snapshots/external/388a13d71284b1a4b0c457e9c8d1ec60dfefb8871c69ceb1d7a035bd3bdadab8.html new file mode 100644 index 00000000..1232ad5e --- /dev/null +++ b/tests/snapshots/external/388a13d71284b1a4b0c457e9c8d1ec60dfefb8871c69ceb1d7a035bd3bdadab8.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/3d072a22b9513eecb51c6a5f39b978c1c1d3ef56a572031a307fe1cad1f17eff.html b/tests/snapshots/external/3d072a22b9513eecb51c6a5f39b978c1c1d3ef56a572031a307fe1cad1f17eff.html new file mode 100644 index 00000000..f950f69b --- /dev/null +++ b/tests/snapshots/external/3d072a22b9513eecb51c6a5f39b978c1c1d3ef56a572031a307fe1cad1f17eff.html @@ -0,0 +1,324 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/3f5d794823a451ec9d4ed8c7e16d1354d39b74380402b255ee60741e97c9960c.html b/tests/snapshots/external/3f5d794823a451ec9d4ed8c7e16d1354d39b74380402b255ee60741e97c9960c.html new file mode 100644 index 00000000..8b4491f3 --- /dev/null +++ b/tests/snapshots/external/3f5d794823a451ec9d4ed8c7e16d1354d39b74380402b255ee60741e97c9960c.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/42c053a5e567a777dfde62cd0d061112dc8098f90e71f71d5aceba8be188fcf7.html b/tests/snapshots/external/42c053a5e567a777dfde62cd0d061112dc8098f90e71f71d5aceba8be188fcf7.html new file mode 100644 index 00000000..52ada349 --- /dev/null +++ b/tests/snapshots/external/42c053a5e567a777dfde62cd0d061112dc8098f90e71f71d5aceba8be188fcf7.html @@ -0,0 +1,26 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html b/tests/snapshots/external/4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html new file mode 100644 index 00000000..c70d8ae8 --- /dev/null +++ b/tests/snapshots/external/4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html @@ -0,0 +1,97 @@ + + +
+

+ + signature_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + __init__ + +

+
+ 
__init__(a, b)
+
+
+
+

+ Docstring for `Class. + + init + + . +

+
+
+
+

+ + method1 + +

+
+ 
method1(a, b)
+
+
+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + module_function + +

+
+ 
module_function(a, b)
+
+
+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/44e42f27bfe3d3b5ec14700c247c83195b1c6eea319d1a0679b2baa797d9859c.html b/tests/snapshots/external/44e42f27bfe3d3b5ec14700c247c83195b1c6eea319d1a0679b2baa797d9859c.html new file mode 100644 index 00000000..2bfbdbf4 --- /dev/null +++ b/tests/snapshots/external/44e42f27bfe3d3b5ec14700c247c83195b1c6eea319d1a0679b2baa797d9859c.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/46e56f39b10d1e8ee4017bc11457bf76d169fc80b3d3e465213671b7f6e548eb.html b/tests/snapshots/external/46e56f39b10d1e8ee4017bc11457bf76d169fc80b3d3e465213671b7f6e548eb.html new file mode 100644 index 00000000..36f35fb4 --- /dev/null +++ b/tests/snapshots/external/46e56f39b10d1e8ee4017bc11457bf76d169fc80b3d3e465213671b7f6e548eb.html @@ -0,0 +1,132 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/4892e0fe1920c0bb22fa4787b6e76cccaa968163b35641d705f288c04fe4937e.html b/tests/snapshots/external/4892e0fe1920c0bb22fa4787b6e76cccaa968163b35641d705f288c04fe4937e.html new file mode 100644 index 00000000..3b41766d --- /dev/null +++ b/tests/snapshots/external/4892e0fe1920c0bb22fa4787b6e76cccaa968163b35641d705f288c04fe4937e.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/4f60da13e2d45e803f73ed41746d8b3570f0dac7e132efb1bf0cdbf77e9e2c59.html b/tests/snapshots/external/4f60da13e2d45e803f73ed41746d8b3570f0dac7e132efb1bf0cdbf77e9e2c59.html new file mode 100644 index 00000000..7d734fba --- /dev/null +++ b/tests/snapshots/external/4f60da13e2d45e803f73ed41746d8b3570f0dac7e132efb1bf0cdbf77e9e2c59.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/59a9e1ffb2f0807b594a933444c78753a06f359527ea4adac85c72a7812b21d3.html b/tests/snapshots/external/59a9e1ffb2f0807b594a933444c78753a06f359527ea4adac85c72a7812b21d3.html new file mode 100644 index 00000000..ad60041c --- /dev/null +++ b/tests/snapshots/external/59a9e1ffb2f0807b594a933444c78753a06f359527ea4adac85c72a7812b21d3.html @@ -0,0 +1,318 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/5a9c10410801aa75b33878971b939da701df9a7ce8006dc7781c148d27a89756.html b/tests/snapshots/external/5a9c10410801aa75b33878971b939da701df9a7ce8006dc7781c148d27a89756.html new file mode 100644 index 00000000..8fd78409 --- /dev/null +++ b/tests/snapshots/external/5a9c10410801aa75b33878971b939da701df9a7ce8006dc7781c148d27a89756.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/5cf0130e3b4fdd536b1c99ee66c66ec4245e286bf75b989cf50979ce187e1a16.html b/tests/snapshots/external/5cf0130e3b4fdd536b1c99ee66c66ec4245e286bf75b989cf50979ce187e1a16.html new file mode 100644 index 00000000..eb15c707 --- /dev/null +++ b/tests/snapshots/external/5cf0130e3b4fdd536b1c99ee66c66ec4245e286bf75b989cf50979ce187e1a16.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/62e18d3e57777d911c7fdee1fcc032a9c23ffe82913060e3b66f29bf81a6a585.html b/tests/snapshots/external/62e18d3e57777d911c7fdee1fcc032a9c23ffe82913060e3b66f29bf81a6a585.html new file mode 100644 index 00000000..1a8842f9 --- /dev/null +++ b/tests/snapshots/external/62e18d3e57777d911c7fdee1fcc032a9c23ffe82913060e3b66f29bf81a6a585.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/6a02b544c12c68b75d9bf3b85b1800830fd980daabff9df8c3760eb6edea7915.html b/tests/snapshots/external/6a02b544c12c68b75d9bf3b85b1800830fd980daabff9df8c3760eb6edea7915.html new file mode 100644 index 00000000..70567c97 --- /dev/null +++ b/tests/snapshots/external/6a02b544c12c68b75d9bf3b85b1800830fd980daabff9df8c3760eb6edea7915.html @@ -0,0 +1,136 @@ + + +
+

+ + signature_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for `Class. + + init + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/6d12192d6b4dc0633bad697a683a3cdf3b2b9ceeb839044c72c63b469914f0a1.html b/tests/snapshots/external/6d12192d6b4dc0633bad697a683a3cdf3b2b9ceeb839044c72c63b469914f0a1.html new file mode 100644 index 00000000..93503606 --- /dev/null +++ b/tests/snapshots/external/6d12192d6b4dc0633bad697a683a3cdf3b2b9ceeb839044c72c63b469914f0a1.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/7107066872137b807b3f9d897e75eff78f5783b14d3c88e71c6477eaa8493113.html b/tests/snapshots/external/7107066872137b807b3f9d897e75eff78f5783b14d3c88e71c6477eaa8493113.html new file mode 100644 index 00000000..27fcc6c1 --- /dev/null +++ b/tests/snapshots/external/7107066872137b807b3f9d897e75eff78f5783b14d3c88e71c6477eaa8493113.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/728c1344630190ac84514ebd8e5ae2d95ba8685e16d2c79749f675b5b2a6cea5.html b/tests/snapshots/external/728c1344630190ac84514ebd8e5ae2d95ba8685e16d2c79749f675b5b2a6cea5.html new file mode 100644 index 00000000..d6ac202a --- /dev/null +++ b/tests/snapshots/external/728c1344630190ac84514ebd8e5ae2d95ba8685e16d2c79749f675b5b2a6cea5.html @@ -0,0 +1,289 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/735fc6ffdb82ce35cdab2aed2389a630e4d2c7ad95308bc5c7a56a8a8930b37f.html b/tests/snapshots/external/735fc6ffdb82ce35cdab2aed2389a630e4d2c7ad95308bc5c7a56a8a8930b37f.html new file mode 100644 index 00000000..44516fe5 --- /dev/null +++ b/tests/snapshots/external/735fc6ffdb82ce35cdab2aed2389a630e4d2c7ad95308bc5c7a56a8a8930b37f.html @@ -0,0 +1,190 @@ + + +
+

+ + signature_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + __init__ + + + ( + + + a + + + : + + + int + + + , + + + b + + + : + + + str + + + ) + + + -> + + + None + + +

+
+

+ Docstring for `Class. + + init + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + : + + + int + + + , + + + b + + + : + + + str + + + ) + + + -> + + + None + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + : + + + int + + + , + + + b + + + : + + + str + + + ) + + + -> + + + None + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/74bfab19cbd4ba02673f6b9ee736a3b6727936de92f73f299ba238491f619937.html b/tests/snapshots/external/74bfab19cbd4ba02673f6b9ee736a3b6727936de92f73f299ba238491f619937.html new file mode 100644 index 00000000..3ae3af4d --- /dev/null +++ b/tests/snapshots/external/74bfab19cbd4ba02673f6b9ee736a3b6727936de92f73f299ba238491f619937.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/76ee8e01e1c0b94de84d79da8443bc24f601f89cab70eae1b2af5ee21cfb1f3a.html b/tests/snapshots/external/76ee8e01e1c0b94de84d79da8443bc24f601f89cab70eae1b2af5ee21cfb1f3a.html new file mode 100644 index 00000000..bed00768 --- /dev/null +++ b/tests/snapshots/external/76ee8e01e1c0b94de84d79da8443bc24f601f89cab70eae1b2af5ee21cfb1f3a.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/7c988c9e13efeadd20b911a95cc69973b715cceacdadefc540109aad3c274bde.html b/tests/snapshots/external/7c988c9e13efeadd20b911a95cc69973b715cceacdadefc540109aad3c274bde.html new file mode 100644 index 00000000..10b98188 --- /dev/null +++ b/tests/snapshots/external/7c988c9e13efeadd20b911a95cc69973b715cceacdadefc540109aad3c274bde.html @@ -0,0 +1,508 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/7d5fe66539191786245991395e77d8ba0bbb22330cb08eaec2e84159bde4159b.html b/tests/snapshots/external/7d5fe66539191786245991395e77d8ba0bbb22330cb08eaec2e84159bde4159b.html new file mode 100644 index 00000000..23e38eeb --- /dev/null +++ b/tests/snapshots/external/7d5fe66539191786245991395e77d8ba0bbb22330cb08eaec2e84159bde4159b.html @@ -0,0 +1,353 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/83119803338105f101311992d31947e4fcaf2c5a6c68cad6355d8611c1cc2e3f.html b/tests/snapshots/external/83119803338105f101311992d31947e4fcaf2c5a6c68cad6355d8611c1cc2e3f.html new file mode 100644 index 00000000..c9c637e4 --- /dev/null +++ b/tests/snapshots/external/83119803338105f101311992d31947e4fcaf2c5a6c68cad6355d8611c1cc2e3f.html @@ -0,0 +1,318 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/88855b0284174733b57edd2043e0e8cd6a1a0223055f08b80031452eb05d9484.html b/tests/snapshots/external/88855b0284174733b57edd2043e0e8cd6a1a0223055f08b80031452eb05d9484.html new file mode 100644 index 00000000..540a2f6a --- /dev/null +++ b/tests/snapshots/external/88855b0284174733b57edd2043e0e8cd6a1a0223055f08b80031452eb05d9484.html @@ -0,0 +1,318 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/8b097c69ac2fd52857f33e1b008f4d99a53ed21894c51517b3d79da445b0a705.html b/tests/snapshots/external/8b097c69ac2fd52857f33e1b008f4d99a53ed21894c51517b3d79da445b0a705.html new file mode 100644 index 00000000..e908da32 --- /dev/null +++ b/tests/snapshots/external/8b097c69ac2fd52857f33e1b008f4d99a53ed21894c51517b3d79da445b0a705.html @@ -0,0 +1,59 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/8d4e1f9af9971bd21234c7c45dfbd59a1aee444bfa0cd3b9cfb6d052d378a041.html b/tests/snapshots/external/8d4e1f9af9971bd21234c7c45dfbd59a1aee444bfa0cd3b9cfb6d052d378a041.html new file mode 100644 index 00000000..eb755e52 --- /dev/null +++ b/tests/snapshots/external/8d4e1f9af9971bd21234c7c45dfbd59a1aee444bfa0cd3b9cfb6d052d378a041.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/955e5111f4262f280b0787a22dfa46c9ea93c80bc49e1a1de100349341d93fb9.html b/tests/snapshots/external/955e5111f4262f280b0787a22dfa46c9ea93c80bc49e1a1de100349341d93fb9.html new file mode 100644 index 00000000..ee00ece7 --- /dev/null +++ b/tests/snapshots/external/955e5111f4262f280b0787a22dfa46c9ea93c80bc49e1a1de100349341d93fb9.html @@ -0,0 +1,97 @@ + + +
+

+ + signature_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + __init__ + +

+
+ 
__init__(a: int, b: str) -> None
+
+
+
+

+ Docstring for `Class. + + init + + . +

+
+
+
+

+ + method1 + +

+
+ 
method1(a: int, b: str) -> None
+
+
+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + module_function + +

+
+ 
module_function(a: int, b: str) -> None
+
+
+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/95f8e480937f7a2b956392ed4d8058052d9748874cdd911feacdd31d1abe5d97.html b/tests/snapshots/external/95f8e480937f7a2b956392ed4d8058052d9748874cdd911feacdd31d1abe5d97.html new file mode 100644 index 00000000..f827f125 --- /dev/null +++ b/tests/snapshots/external/95f8e480937f7a2b956392ed4d8058052d9748874cdd911feacdd31d1abe5d97.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/96cf94f4822a5cf5d72407eab5a5dddda972f16623f7710f738ffe2bcf9130d9.html b/tests/snapshots/external/96cf94f4822a5cf5d72407eab5a5dddda972f16623f7710f738ffe2bcf9130d9.html new file mode 100644 index 00000000..9aa9c3c1 --- /dev/null +++ b/tests/snapshots/external/96cf94f4822a5cf5d72407eab5a5dddda972f16623f7710f738ffe2bcf9130d9.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/981438492e387bc82b23f09e3c5e0b452db5a1ffd88e52479db2b52a170fd8f9.html b/tests/snapshots/external/981438492e387bc82b23f09e3c5e0b452db5a1ffd88e52479db2b52a170fd8f9.html new file mode 100644 index 00000000..574ec87c --- /dev/null +++ b/tests/snapshots/external/981438492e387bc82b23f09e3c5e0b452db5a1ffd88e52479db2b52a170fd8f9.html @@ -0,0 +1,506 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/9bd282a6f2fe82f3ffe66b175bf90ab3e808e3a67f3c15a9f9e3e143d7956e49.html b/tests/snapshots/external/9bd282a6f2fe82f3ffe66b175bf90ab3e808e3a67f3c15a9f9e3e143d7956e49.html new file mode 100644 index 00000000..ce4ee8a7 --- /dev/null +++ b/tests/snapshots/external/9bd282a6f2fe82f3ffe66b175bf90ab3e808e3a67f3c15a9f9e3e143d7956e49.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html b/tests/snapshots/external/9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html new file mode 100644 index 00000000..6dd48d30 --- /dev/null +++ b/tests/snapshots/external/9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html @@ -0,0 +1,97 @@ + + +
+

+ + signature_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + __init__ + +

+
+ 
__init__(a, b)
+
+
+
+

+ Docstring for `Class. + + init + + . +

+
+
+
+

+ + method1 + +

+
+ 
method1(a, b)
+
+
+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + module_function + +

+
+ 
module_function(a, b)
+
+
+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/9d03089a46fab9a86b0836444cabb6225798eaf25be6fd4171bd73b7354509b6.html b/tests/snapshots/external/9d03089a46fab9a86b0836444cabb6225798eaf25be6fd4171bd73b7354509b6.html new file mode 100644 index 00000000..0ee900fb --- /dev/null +++ b/tests/snapshots/external/9d03089a46fab9a86b0836444cabb6225798eaf25be6fd4171bd73b7354509b6.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/a1167b14f5a71a283817bf5866d2bb0bd08bf23dc054c6f7938a04f42feab99d.html b/tests/snapshots/external/a1167b14f5a71a283817bf5866d2bb0bd08bf23dc054c6f7938a04f42feab99d.html new file mode 100644 index 00000000..bb9001d8 --- /dev/null +++ b/tests/snapshots/external/a1167b14f5a71a283817bf5866d2bb0bd08bf23dc054c6f7938a04f42feab99d.html @@ -0,0 +1,167 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/a185e216dc7b7ebb31b46ea0e7ed446cf9da94eee8db306f08bae1ca0db0ca1d.html b/tests/snapshots/external/a185e216dc7b7ebb31b46ea0e7ed446cf9da94eee8db306f08bae1ca0db0ca1d.html new file mode 100644 index 00000000..a0685468 --- /dev/null +++ b/tests/snapshots/external/a185e216dc7b7ebb31b46ea0e7ed446cf9da94eee8db306f08bae1ca0db0ca1d.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/a200913d9a7d51c52ab58f6fc4e9ea7be278d7890c46cf28ecc3cfd35a36fb46.html b/tests/snapshots/external/a200913d9a7d51c52ab58f6fc4e9ea7be278d7890c46cf28ecc3cfd35a36fb46.html new file mode 100644 index 00000000..96cff9d7 --- /dev/null +++ b/tests/snapshots/external/a200913d9a7d51c52ab58f6fc4e9ea7be278d7890c46cf28ecc3cfd35a36fb46.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/a2c5be9bd5d1f0db3ff64b44353c1760f5eb69d7db6401da2f28518d0e8065c4.html b/tests/snapshots/external/a2c5be9bd5d1f0db3ff64b44353c1760f5eb69d7db6401da2f28518d0e8065c4.html new file mode 100644 index 00000000..4738a584 --- /dev/null +++ b/tests/snapshots/external/a2c5be9bd5d1f0db3ff64b44353c1760f5eb69d7db6401da2f28518d0e8065c4.html @@ -0,0 +1,318 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/ab0ddac637b536c06014746a4a8f8e0921b074015ae19680abf5df995c233ba1.html b/tests/snapshots/external/ab0ddac637b536c06014746a4a8f8e0921b074015ae19680abf5df995c233ba1.html new file mode 100644 index 00000000..3933bd9d --- /dev/null +++ b/tests/snapshots/external/ab0ddac637b536c06014746a4a8f8e0921b074015ae19680abf5df995c233ba1.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/ae74b5980f9b6996ed6e112d53168fde16c32d92bed42fb3193f98e0e3f04602.html b/tests/snapshots/external/ae74b5980f9b6996ed6e112d53168fde16c32d92bed42fb3193f98e0e3f04602.html new file mode 100644 index 00000000..34123ecf --- /dev/null +++ b/tests/snapshots/external/ae74b5980f9b6996ed6e112d53168fde16c32d92bed42fb3193f98e0e3f04602.html @@ -0,0 +1,353 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/afd5c166367dd47e4f9843d906b3a1ad12398888fdad84bfbda3de8b19072611.html b/tests/snapshots/external/afd5c166367dd47e4f9843d906b3a1ad12398888fdad84bfbda3de8b19072611.html new file mode 100644 index 00000000..8501bce2 --- /dev/null +++ b/tests/snapshots/external/afd5c166367dd47e4f9843d906b3a1ad12398888fdad84bfbda3de8b19072611.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/b060b701543e5503dc848538a164e80480ab25f8885aa83b97776e6b0cc6b570.html b/tests/snapshots/external/b060b701543e5503dc848538a164e80480ab25f8885aa83b97776e6b0cc6b570.html new file mode 100644 index 00000000..599197fe --- /dev/null +++ b/tests/snapshots/external/b060b701543e5503dc848538a164e80480ab25f8885aa83b97776e6b0cc6b570.html @@ -0,0 +1,136 @@ + + +
+

+ + signature_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for `Class. + + init + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/b0a9b08f1f721721c4dd110cb8f85ffda5caf1f1479851275bc227857fb01400.html b/tests/snapshots/external/b0a9b08f1f721721c4dd110cb8f85ffda5caf1f1479851275bc227857fb01400.html new file mode 100644 index 00000000..bbd48b9e --- /dev/null +++ b/tests/snapshots/external/b0a9b08f1f721721c4dd110cb8f85ffda5caf1f1479851275bc227857fb01400.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/b4b490164ab1a724cac7aba25bbc69a33e7dd44500e9337718cd96da1bb56325.html b/tests/snapshots/external/b4b490164ab1a724cac7aba25bbc69a33e7dd44500e9337718cd96da1bb56325.html new file mode 100644 index 00000000..9f5cbef9 --- /dev/null +++ b/tests/snapshots/external/b4b490164ab1a724cac7aba25bbc69a33e7dd44500e9337718cd96da1bb56325.html @@ -0,0 +1,320 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/ba51e100acd4f6ad91f1ef484aa5f1bd537e661588b1742d93d0a6543cc3592c.html b/tests/snapshots/external/ba51e100acd4f6ad91f1ef484aa5f1bd537e661588b1742d93d0a6543cc3592c.html new file mode 100644 index 00000000..b18eb50e --- /dev/null +++ b/tests/snapshots/external/ba51e100acd4f6ad91f1ef484aa5f1bd537e661588b1742d93d0a6543cc3592c.html @@ -0,0 +1,477 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/bd6594ae3b516bf84cd0b0e6605087f430f62d787c32225ac8b4039c92e20b76.html b/tests/snapshots/external/bd6594ae3b516bf84cd0b0e6605087f430f62d787c32225ac8b4039c92e20b76.html new file mode 100644 index 00000000..aa4ebf15 --- /dev/null +++ b/tests/snapshots/external/bd6594ae3b516bf84cd0b0e6605087f430f62d787c32225ac8b4039c92e20b76.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/c260e7f4ef3b8b228bb25879d3adcf6610f1c2c971c9c46b5665d276716b8821.html b/tests/snapshots/external/c260e7f4ef3b8b228bb25879d3adcf6610f1c2c971c9c46b5665d276716b8821.html new file mode 100644 index 00000000..fb55bdd1 --- /dev/null +++ b/tests/snapshots/external/c260e7f4ef3b8b228bb25879d3adcf6610f1c2c971c9c46b5665d276716b8821.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/c6e7ef9564cdc8449a98c0ef790d652dee02c47b1339f858fc1d7a54aae9ed46.html b/tests/snapshots/external/c6e7ef9564cdc8449a98c0ef790d652dee02c47b1339f858fc1d7a54aae9ed46.html new file mode 100644 index 00000000..e96d72c3 --- /dev/null +++ b/tests/snapshots/external/c6e7ef9564cdc8449a98c0ef790d652dee02c47b1339f858fc1d7a54aae9ed46.html @@ -0,0 +1,26 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/c915eb92fd5dcc4e2c9da41ca72c726e65fcd85804942be0c67b4f05f452a549.html b/tests/snapshots/external/c915eb92fd5dcc4e2c9da41ca72c726e65fcd85804942be0c67b4f05f452a549.html new file mode 100644 index 00000000..26f0f5ef --- /dev/null +++ b/tests/snapshots/external/c915eb92fd5dcc4e2c9da41ca72c726e65fcd85804942be0c67b4f05f452a549.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/c9a15552eed32a233795c2086a7c766ad95e05197d30d881540fbe52cdc07ff8.html b/tests/snapshots/external/c9a15552eed32a233795c2086a7c766ad95e05197d30d881540fbe52cdc07ff8.html new file mode 100644 index 00000000..79a5ff40 --- /dev/null +++ b/tests/snapshots/external/c9a15552eed32a233795c2086a7c766ad95e05197d30d881540fbe52cdc07ff8.html @@ -0,0 +1,55 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/cc19537fdba4a26b10c60d5586b0eb7ef0264a783a3c47d1114d21fa8cfa3947.html b/tests/snapshots/external/cc19537fdba4a26b10c60d5586b0eb7ef0264a783a3c47d1114d21fa8cfa3947.html new file mode 100644 index 00000000..f93ae024 --- /dev/null +++ b/tests/snapshots/external/cc19537fdba4a26b10c60d5586b0eb7ef0264a783a3c47d1114d21fa8cfa3947.html @@ -0,0 +1,506 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/cdc8126d78b690d11c09e3128df0f8d65379375a6bd390da30f5676bf2289cf2.html b/tests/snapshots/external/cdc8126d78b690d11c09e3128df0f8d65379375a6bd390da30f5676bf2289cf2.html new file mode 100644 index 00000000..158c1ca5 --- /dev/null +++ b/tests/snapshots/external/cdc8126d78b690d11c09e3128df0f8d65379375a6bd390da30f5676bf2289cf2.html @@ -0,0 +1,289 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/ce06da7f07b34e4f9071c5c001a8626f2d5fd8eed9a3ba81abebd76f8afc6861.html b/tests/snapshots/external/ce06da7f07b34e4f9071c5c001a8626f2d5fd8eed9a3ba81abebd76f8afc6861.html new file mode 100644 index 00000000..898bab70 --- /dev/null +++ b/tests/snapshots/external/ce06da7f07b34e4f9071c5c001a8626f2d5fd8eed9a3ba81abebd76f8afc6861.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/cfcd41685591bcc497f9d1e9fd20006fc3acd857f068e78e6d1c2461bbd4063f.html b/tests/snapshots/external/cfcd41685591bcc497f9d1e9fd20006fc3acd857f068e78e6d1c2461bbd4063f.html new file mode 100644 index 00000000..d543f794 --- /dev/null +++ b/tests/snapshots/external/cfcd41685591bcc497f9d1e9fd20006fc3acd857f068e78e6d1c2461bbd4063f.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/d1216ebf8e30ec559861678318efb45bef54a847517e5d90e130818c2a06b163.html b/tests/snapshots/external/d1216ebf8e30ec559861678318efb45bef54a847517e5d90e130818c2a06b163.html new file mode 100644 index 00000000..65e87e01 --- /dev/null +++ b/tests/snapshots/external/d1216ebf8e30ec559861678318efb45bef54a847517e5d90e130818c2a06b163.html @@ -0,0 +1,190 @@ + + +
+

+ + signature_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + __init__ + + + ( + + + a + + + : + + + int + + + , + + + b + + + : + + + str + + + ) + + + -> + + + None + + +

+
+

+ Docstring for `Class. + + init + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + : + + + int + + + , + + + b + + + : + + + str + + + ) + + + -> + + + None + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + : + + + int + + + , + + + b + + + : + + + str + + + ) + + + -> + + + None + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/d540895f6bf91c8c8e4abc02f40529a61c6cec71b18da2e4f02206ec18b901ef.html b/tests/snapshots/external/d540895f6bf91c8c8e4abc02f40529a61c6cec71b18da2e4f02206ec18b901ef.html new file mode 100644 index 00000000..2ad1c277 --- /dev/null +++ b/tests/snapshots/external/d540895f6bf91c8c8e4abc02f40529a61c6cec71b18da2e4f02206ec18b901ef.html @@ -0,0 +1,353 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/d5a6bf59c663338bef9fdc2391f482aee444228e86e23357c11881498e711bb2.html b/tests/snapshots/external/d5a6bf59c663338bef9fdc2391f482aee444228e86e23357c11881498e711bb2.html new file mode 100644 index 00000000..23e66fd7 --- /dev/null +++ b/tests/snapshots/external/d5a6bf59c663338bef9fdc2391f482aee444228e86e23357c11881498e711bb2.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/d726cb8367d95b67ce78e718e88ee528d3abc2fbd04413d1c11916a243d7567a.html b/tests/snapshots/external/d726cb8367d95b67ce78e718e88ee528d3abc2fbd04413d1c11916a243d7567a.html new file mode 100644 index 00000000..1f45fb80 --- /dev/null +++ b/tests/snapshots/external/d726cb8367d95b67ce78e718e88ee528d3abc2fbd04413d1c11916a243d7567a.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/e3defc3620e5fee20f9400c33b7b541fde66297f257d9baf1b0f94b3ea49e6e0.html b/tests/snapshots/external/e3defc3620e5fee20f9400c33b7b541fde66297f257d9baf1b0f94b3ea49e6e0.html new file mode 100644 index 00000000..8c035cc8 --- /dev/null +++ b/tests/snapshots/external/e3defc3620e5fee20f9400c33b7b541fde66297f257d9baf1b0f94b3ea49e6e0.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/e6a9b76f268cde81a129e7273038db0ff3fcd73530442a30c48cf01dcbc30aaa.html b/tests/snapshots/external/e6a9b76f268cde81a129e7273038db0ff3fcd73530442a30c48cf01dcbc30aaa.html new file mode 100644 index 00000000..dbcf8c57 --- /dev/null +++ b/tests/snapshots/external/e6a9b76f268cde81a129e7273038db0ff3fcd73530442a30c48cf01dcbc30aaa.html @@ -0,0 +1,318 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/e8be7a9b1410e40dac79fe0ee29d3036e707a177b2ba2bdad25a6998bec570b7.html b/tests/snapshots/external/e8be7a9b1410e40dac79fe0ee29d3036e707a177b2ba2bdad25a6998bec570b7.html new file mode 100644 index 00000000..3dbd9879 --- /dev/null +++ b/tests/snapshots/external/e8be7a9b1410e40dac79fe0ee29d3036e707a177b2ba2bdad25a6998bec570b7.html @@ -0,0 +1,506 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/e90c3e0c85ddaa068f3d063c6a1ef718bb3ae2092760b707e838fb73164b3720.html b/tests/snapshots/external/e90c3e0c85ddaa068f3d063c6a1ef718bb3ae2092760b707e838fb73164b3720.html new file mode 100644 index 00000000..a6ee2831 --- /dev/null +++ b/tests/snapshots/external/e90c3e0c85ddaa068f3d063c6a1ef718bb3ae2092760b707e838fb73164b3720.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/eee65d3705a655eec6512c4aa09d55f5d2e7c62dd245fed4b3f002a5e9a4d646.html b/tests/snapshots/external/eee65d3705a655eec6512c4aa09d55f5d2e7c62dd245fed4b3f002a5e9a4d646.html new file mode 100644 index 00000000..53b5e455 --- /dev/null +++ b/tests/snapshots/external/eee65d3705a655eec6512c4aa09d55f5d2e7c62dd245fed4b3f002a5e9a4d646.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/f0014d9505eceb38ba1e36c380a97ebe4d43669929ec1cdedba4d418899aecc7.html b/tests/snapshots/external/f0014d9505eceb38ba1e36c380a97ebe4d43669929ec1cdedba4d418899aecc7.html new file mode 100644 index 00000000..5fbd6650 --- /dev/null +++ b/tests/snapshots/external/f0014d9505eceb38ba1e36c380a97ebe4d43669929ec1cdedba4d418899aecc7.html @@ -0,0 +1,26 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/f3f3acb6b51ba98f5a06e7c62e85b791b6521504f19a8d7496592dee59c7f199.html b/tests/snapshots/external/f3f3acb6b51ba98f5a06e7c62e85b791b6521504f19a8d7496592dee59c7f199.html new file mode 100644 index 00000000..48c42b3d --- /dev/null +++ b/tests/snapshots/external/f3f3acb6b51ba98f5a06e7c62e85b791b6521504f19a8d7496592dee59c7f199.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html b/tests/snapshots/external/f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html new file mode 100644 index 00000000..08ae8776 --- /dev/null +++ b/tests/snapshots/external/f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html @@ -0,0 +1,97 @@ + + +
+

+ + signature_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + __init__ + +

+
+ 
__init__(a: int, b: str) -> None
+
+
+
+

+ Docstring for `Class. + + init + + . +

+
+
+
+

+ + method1 + +

+
+ 
method1(a: int, b: str) -> None
+
+
+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + module_function + +

+
+ 
module_function(a: int, b: str) -> None
+
+
+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/f6e292b8358a04e3471ba11c8820307076be3cf83b0a9ec2fb5c949324b7e172.html b/tests/snapshots/external/f6e292b8358a04e3471ba11c8820307076be3cf83b0a9ec2fb5c949324b7e172.html new file mode 100644 index 00000000..79900273 --- /dev/null +++ b/tests/snapshots/external/f6e292b8358a04e3471ba11c8820307076be3cf83b0a9ec2fb5c949324b7e172.html @@ -0,0 +1,57 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/f7711b8af7689b331209f8c034c8cc3a2ec894372644a8eaee597418e9b55b3c.html b/tests/snapshots/external/f7711b8af7689b331209f8c034c8cc3a2ec894372644a8eaee597418e9b55b3c.html new file mode 100644 index 00000000..522fd1c1 --- /dev/null +++ b/tests/snapshots/external/f7711b8af7689b331209f8c034c8cc3a2ec894372644a8eaee597418e9b55b3c.html @@ -0,0 +1,318 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/f77f1c850398f972a7ae2229f918ba497874115be6c5e9431838b4bb6931b2f4.html b/tests/snapshots/external/f77f1c850398f972a7ae2229f918ba497874115be6c5e9431838b4bb6931b2f4.html new file mode 100644 index 00000000..4be85a18 --- /dev/null +++ b/tests/snapshots/external/f77f1c850398f972a7ae2229f918ba497874115be6c5e9431838b4bb6931b2f4.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/f848d4a9e516beeb1b1719630e34aa243a093ccd362a63e33dbd6202ae8ab75d.html b/tests/snapshots/external/f848d4a9e516beeb1b1719630e34aa243a093ccd362a63e33dbd6202ae8ab75d.html new file mode 100644 index 00000000..19c29b39 --- /dev/null +++ b/tests/snapshots/external/f848d4a9e516beeb1b1719630e34aa243a093ccd362a63e33dbd6202ae8ab75d.html @@ -0,0 +1,353 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/f8f32ea6a0c80a63854f8c8d78b3706797feb3042ac88c8fcf0a6da277eddb9d.html b/tests/snapshots/external/f8f32ea6a0c80a63854f8c8d78b3706797feb3042ac88c8fcf0a6da277eddb9d.html new file mode 100644 index 00000000..d1e4f8bd --- /dev/null +++ b/tests/snapshots/external/f8f32ea6a0c80a63854f8c8d78b3706797feb3042ac88c8fcf0a6da277eddb9d.html @@ -0,0 +1,26 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/fb5ebb7546d8d63744d7e6713ab5317b8c3d00d1108d28d7ef2949994b41dcbd.html b/tests/snapshots/external/fb5ebb7546d8d63744d7e6713ab5317b8c3d00d1108d28d7ef2949994b41dcbd.html new file mode 100644 index 00000000..ec61d8e3 --- /dev/null +++ b/tests/snapshots/external/fb5ebb7546d8d63744d7e6713ab5317b8c3d00d1108d28d7ef2949994b41dcbd.html @@ -0,0 +1,24 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/fb65efbbfc3ef9c2a06e6f539f8a75bec4276e61254539632a1d5f8f2c6c3452.html b/tests/snapshots/external/fb65efbbfc3ef9c2a06e6f539f8a75bec4276e61254539632a1d5f8f2c6c3452.html new file mode 100644 index 00000000..3cec9af8 --- /dev/null +++ b/tests/snapshots/external/fb65efbbfc3ef9c2a06e6f539f8a75bec4276e61254539632a1d5f8f2c6c3452.html @@ -0,0 +1,318 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+

+ + + module_attribute + + + = + + + 42 + + + + + + module-attribute + + + +

+
+

+ Docstring for + + module_attribute + + . +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + class_attribute + + + = + + + 42 + + + + + + class-attribute + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.class_attribute + + . +

+
+
+
+

+ + + instance_attribute + + + = + + + a + + + + + + + b + + + + + + instance-attribute + + + +

+
+

+ Docstring for + + Class.instance_attribute + + . +

+
+
+
+

+ + NestedClass + +

+
+

+ Docstring for + + NestedClass + + . +

+
+
+
+

+ + + __init__ + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.__init__ + + . +

+
+
+
+

+ + + method1 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method1 + + . +

+
+
+
+

+ + + method2 + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.method2 + + . +

+
+
+
+
+
+
+

+ + Subclass + +

+
+

+ Bases: + + + Class + + +

+

+ Docstring for + + Subclass + + . +

+
+
+
+
+
+

+ + + module_function + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + module_function + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/fb770e6537bc1b98c0de03db7810404967562a2ffd1700ca35c9788949ca55c0.html b/tests/snapshots/external/fb770e6537bc1b98c0de03db7810404967562a2ffd1700ca35c9788949ca55c0.html new file mode 100644 index 00000000..0ed1d57b --- /dev/null +++ b/tests/snapshots/external/fb770e6537bc1b98c0de03db7810404967562a2ffd1700ca35c9788949ca55c0.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/snapshots/external/fba0d78ae23e4f52b5e6f0fe003ea3edf681a937f647b11925e9932006648a11.html b/tests/snapshots/external/fba0d78ae23e4f52b5e6f0fe003ea3edf681a937f647b11925e9932006648a11.html new file mode 100644 index 00000000..ff8087d4 --- /dev/null +++ b/tests/snapshots/external/fba0d78ae23e4f52b5e6f0fe003ea3edf681a937f647b11925e9932006648a11.html @@ -0,0 +1,22 @@ + + +
+

+ + members_package + +

+
+

+ Docstring for the package. +

+
+
+
+
diff --git a/tests/test_end_to_end.py b/tests/test_end_to_end.py new file mode 100644 index 00000000..05dcfeb3 --- /dev/null +++ b/tests/test_end_to_end.py @@ -0,0 +1,168 @@ +"""End-to-end tests for every combination of options.""" + +from __future__ import annotations + +import json +import re +from typing import TYPE_CHECKING, Any + +import bs4 +import pytest +from griffe import LinesCollection, ModulesCollection, TmpPackage, temporary_pypackage +from inline_snapshot import outsource + +from tests.snapshots import snapshots_members, snapshots_signatures + +if TYPE_CHECKING: + from collections.abc import Iterator + + from mkdocstrings_handlers.python.handler import PythonHandler + + +def _normalize_html(html: str) -> str: + soup = bs4.BeautifulSoup(html, features="html.parser") + html = soup.prettify() + html = re.sub(r"\b(0x)[a-f0-9]+\b", r"\1...", html) + html = re.sub(r"^(Build Date UTC ?:).+", r"\1...", html, flags=re.MULTILINE) + html = re.sub(r"\b[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\b", r"...", html) + html = re.sub(r'(?<=id="cell-id=)\w+(?=")', r"...", html) + return html # noqa: RET504 + + +def _render(handler: PythonHandler, package: TmpPackage, final_options: dict[str, Any]) -> str: + final_options.pop("handler", None) + final_options.pop("session_handler", None) + handler_options = final_options.copy() + + # Some default options to make snapshots easier to review. + handler_options.setdefault("heading_level", 1) + handler_options.setdefault("show_root_heading", True) + handler_options.setdefault("show_source", False) + + handler._paths = [str(package.tmpdir)] + try: + data = handler.collect(package.name, handler_options) + finally: + # We're using a session handler, so we need to reset its state after each call. + # This is not thread-safe, but pytest-xdist uses subprocesses, so it's fine. + handler._modules_collection = ModulesCollection() + handler._lines_collection = LinesCollection() + handler._paths = [] + + html = handler.render(data, handler_options) + return _normalize_html(html) + + +def _render_options(options: dict[str, Any]) -> str: + return f"\n\n" + + +# Signature options +@pytest.fixture(name="signature_package", scope="session") +def _signature_package() -> Iterator[TmpPackage]: + code = """ + def module_function(a: int, b: str) -> None: + '''Docstring for `module_function`.''' + + class Class: + '''Docstring for `Class`.''' + + def __init__(self, a: int, b: str) -> None: + '''Docstring for `Class.__init__.''' + + def method1(self, a: int, b: str) -> None: + '''Docstring for `Class.method1`.''' + """ + with temporary_pypackage("signature_package", {"__init__.py": code}) as tmppkg: + yield tmppkg + + +@pytest.mark.parametrize("show_signature_annotations", [True, False]) +@pytest.mark.parametrize("signature_crossrefs", [True, False]) +@pytest.mark.parametrize("separate_signature", [True, False]) +def test_end_to_end_for_signatures( + session_handler: PythonHandler, + signature_package: TmpPackage, + show_signature_annotations: bool, + signature_crossrefs: bool, + separate_signature: bool, +) -> None: + """Test rendering of a given theme's templates. + + Parameters: + identifier: Parametrized identifier. + session_handler: Python handler (fixture). + """ + final_options = { + "show_signature_annotations": show_signature_annotations, + "signature_crossrefs": signature_crossrefs, + "separate_signature": separate_signature, + } + html = _render_options(final_options) + _render(session_handler, signature_package, final_options) + snapshot_key = tuple(sorted(final_options.items())) + assert outsource(html, suffix=".html") == snapshots_signatures[snapshot_key] + + +# Members options. +@pytest.fixture(name="members_package", scope="session") +def _members_package() -> Iterator[TmpPackage]: + code = """ + '''Docstring for the package.''' + + def module_function(a: int, b: str) -> None: + '''Docstring for `module_function`.''' + + class Class: + '''Docstring for `Class`.''' + + class NestedClass: + '''Docstring for `NestedClass`.''' + + class_attribute: int = 42 + '''Docstring for `Class.class_attribute`.''' + + def __init__(self, a: int, b: str) -> None: + '''Docstring for `Class.__init__`.''' + self.instance_attribute = a + b + '''Docstring for `Class.instance_attribute`.''' + + def method1(self, a: int, b: str) -> None: + '''Docstring for `Class.method1`.''' + + def method2(self, a: int, b: str) -> None: + '''Docstring for `Class.method2`.''' + + module_attribute: int = 42 + '''Docstring for `module_attribute`.''' + + class Subclass(Class): + '''Docstring for `Subclass`.''' + """ + with temporary_pypackage("members_package", {"__init__.py": code}) as tmppkg: + yield tmppkg + + +@pytest.mark.parametrize("inherited_members", [(), ("method1",), True, False]) +@pytest.mark.parametrize("members", [(), ("module_attribute",), True, False, None]) +@pytest.mark.parametrize("filters", [(), ("!module_attribute",), ("module_attribute",), None]) +def test_end_to_end_for_members( + session_handler: PythonHandler, + members_package: TmpPackage, + inherited_members: list[str] | bool | None, + members: list[str] | bool | None, + filters: list[str] | None, +) -> None: + """Test rendering of a given theme's templates. + + Parameters: + identifier: Parametrized identifier. + session_handler: Python handler (fixture). + """ + final_options = { + "inherited_members": inherited_members, + "members": members, + "filters": filters, + } + html = _render_options(final_options) + _render(session_handler, members_package, final_options) + snapshot_key = tuple(sorted(final_options.items())) + assert outsource(html, suffix=".html") == snapshots_members[snapshot_key] From 941d0e5fa02038bf4c7ef61633aa8288dc59d1da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 26 Dec 2024 18:58:14 +0100 Subject: [PATCH 018/100] chore: Prepare release 1.13.0 --- CHANGELOG.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c03b29f..ec519312 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,28 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [1.13.0](https://github.com/mkdocstrings/python/releases/tag/1.13.0) - 2024-12-26 + +[Compare with 1.12.2](https://github.com/mkdocstrings/python/compare/1.12.2...1.13.0) + +### Features + +- Allow using Ruff to format signatures and attribute values ([d67215c](https://github.com/mkdocstrings/python/commit/d67215c976938ef1e169f16dd0b6166067ebd7bc) by dm). [PR-216](https://github.com/mkdocstrings/python/pull/216) + +### Bug Fixes + +- Respect `show_signature_annotations` option for attribute signatures in headings ([e93d166](https://github.com/mkdocstrings/python/commit/e93d166a14d0944d30ff2f28f21f2262ac396bff) by Timothée Mazzucotelli). [Issue-griffe-pydantic#9](https://github.com/mkdocstrings/griffe-pydantic/issues/9) +- Handle `__init__` overloads when merging into class ([af6fab3](https://github.com/mkdocstrings/python/commit/af6fab31142204872ace716392dcb314b2cb5d0f) by Timothée Mazzucotelli). [Issue-212](https://github.com/mkdocstrings/python/issues/212) +- Actually check if a module is public when rendering auto-generated summary table for modules ([3bf55b2](https://github.com/mkdocstrings/python/commit/3bf55b22ce9a841242c55b2efcedbd8f3a99ccc9) by Timothée Mazzucotelli). [Issue-203](https://github.com/mkdocstrings/python/issues/203) +- Never render line numbers for signatures and attribute values ([a669f1c](https://github.com/mkdocstrings/python/commit/a669f1caefbd54305cc4610bdd57a529aa1208cf) by Timothée Mazzucotelli). [Issue-192](https://github.com/mkdocstrings/python/issues/192) +- Respect highlight's `linenums` config for `pycon` examples in docstrings ([53eb82a](https://github.com/mkdocstrings/python/commit/53eb82a21bbcaa959306e909bf0d4ac468f87580) by Timothée Mazzucotelli). [Related-to-#192](https://github.com/mkdocstrings/python/issues/192) +- Fix normalization of extension paths on the annoying operating system and Python 3.13 ([101a6dc](https://github.com/mkdocstrings/python/commit/101a6dc428da59a512da617a0a2453f2b6ef4387) by Timothée Mazzucotelli). +- Don't merge parent `__init__` docstring into class docstring if such inherited method wasn't selected through the `inherited_members` configuration option ([6c5b5c3](https://github.com/mkdocstrings/python/commit/6c5b5c341940af9425b3de0672ac400794b3f6e5) by Timothée Mazzucotelli). [Issue-189](https://github.com/mkdocstrings/python/issues/189) + +### Code Refactoring + +- Render `*` and `**` outside of cross-references in signatures ([c4506f0](https://github.com/mkdocstrings/python/commit/c4506f080e0c75cd32d6512c80f5016e82fc12bc) by Timothée Mazzucotelli). [Needed-for-PR-216](https://github.com/mkdocstrings/python/pull/216) + ## [1.12.2](https://github.com/mkdocstrings/python/releases/tag/1.12.2) - 2024-10-19 [Compare with 1.12.1](https://github.com/mkdocstrings/python/compare/1.12.1...1.12.2) From 84ea8a4ad70e3a69fe845ee807367015cce3b5d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 23 Jan 2025 23:51:31 +0100 Subject: [PATCH 019/100] test: Ignore deprecation warning about fallback anchor function --- config/pytest.ini | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/config/pytest.ini b/config/pytest.ini index 9d75f5c6..25f9c92e 100644 --- a/config/pytest.ini +++ b/config/pytest.ini @@ -12,6 +12,4 @@ 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 + ignore:.*fallback anchor function:DeprecationWarning:mkdocstrings From 83823be2146d6a2ecedc5fe9c0cfd84098d780ca Mon Sep 17 00:00:00 2001 From: Uchechukwu Orji Date: Fri, 24 Jan 2025 00:12:18 +0100 Subject: [PATCH 020/100] feat: Add `force_inspection` option to force dynamic analysis Griffe supports this option but mkdocstrings-python didn't allow users to configure it. Issue-94: https://github.com/mkdocstrings/python/issues/94 PR-231: https://github.com/mkdocstrings/python/pull/231 --- docs/usage/configuration/general.md | 24 +++++++++++++++++++++ src/mkdocstrings_handlers/python/handler.py | 3 +++ 2 files changed, 27 insertions(+) diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index e2a6e169..461556bf 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -55,6 +55,30 @@ plugins: //// /// +## `force_inspection` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to force inspecting modules (importing them) even if their source code is available. + +This option is useful when you know that dynamic analysis (inspection) yields better results than static analysis. Do not use this blindly: the recommended approach is to write a Griffe extension that will improve extracted API data. See [How to selectively inspect objects](https://mkdocstrings.github.io/griffe/guide/users/how-to/selectively-inspect/). + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + force_inspection: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + force_inspection: true +``` + ## `show_bases` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 4171fd76..e57ae9e7 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -116,6 +116,7 @@ class PythonHandler(BaseHandler): "annotations_path": "brief", "preload_modules": None, "allow_inspection": True, + "force_inspection": False, "summary": False, "show_labels": True, "unwrap_annotated": False, @@ -127,6 +128,7 @@ class PythonHandler(BaseHandler): Attributes: General options: find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings. Default `False`. allow_inspection (bool): Whether to allow inspecting modules when visiting them is not possible. Default: `True`. + force_inspection (bool): Whether to force using dynamic analysis when loading data. Default: `False`. show_bases (bool): Show the base classes of a class. Default: `True`. show_inheritance_diagram (bool): Show the inheritance diagram of a class using Mermaid. Default: `False`. show_source (bool): Show the source code of this object. Default: `True`. @@ -318,6 +320,7 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem: modules_collection=self._modules_collection, lines_collection=self._lines_collection, allow_inspection=final_config["allow_inspection"], + force_inspection=final_config["force_inspection"], ) try: for pre_loaded_module in final_config.get("preload_modules") or []: From b0b813aa0b30e12afaea23b173da427bb71e6eaa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 29 Jan 2025 15:01:03 +0100 Subject: [PATCH 021/100] style: Remove trailing spaces --- CHANGELOG.md | 6 +++--- docs/.glossary.md | 2 +- docs/.overrides/main.html | 4 ++-- docs/.overrides/partials/comments.html | 2 +- docs/insiders/index.md | 4 ++-- docs/insiders/installation.md | 8 ++++---- docs/usage/configuration/general.md | 2 +- docs/usage/configuration/headings.md | 16 +++++++-------- docs/usage/configuration/signatures.md | 2 +- docs/usage/customization.md | 6 +++--- docs/usage/docstrings/google.md | 4 ++-- docs/usage/index.md | 10 +++++----- .../material/_base/attribute.html.jinja | 12 +++++------ .../material/_base/children.html.jinja | 2 +- .../templates/material/_base/class.html.jinja | 20 +++++++++---------- .../material/_base/docstring.html.jinja | 2 +- .../_base/docstring/admonition.html.jinja | 2 +- .../_base/docstring/attributes.html.jinja | 2 +- .../_base/docstring/classes.html.jinja | 2 +- .../_base/docstring/examples.html.jinja | 2 +- .../_base/docstring/functions.html.jinja | 2 +- .../_base/docstring/modules.html.jinja | 2 +- .../docstring/other_parameters.html.jinja | 2 +- .../_base/docstring/parameters.html.jinja | 2 +- .../_base/docstring/raises.html.jinja | 2 +- .../_base/docstring/receives.html.jinja | 2 +- .../_base/docstring/returns.html.jinja | 2 +- .../material/_base/docstring/warns.html.jinja | 2 +- .../_base/docstring/yields.html.jinja | 2 +- .../material/_base/expression.html.jinja | 4 ++-- .../material/_base/function.html.jinja | 14 ++++++------- .../material/_base/labels.html.jinja | 2 +- .../material/_base/language.html.jinja | 2 +- .../material/_base/languages/en.html.jinja | 2 +- .../material/_base/languages/ja.html.jinja | 2 +- .../material/_base/languages/zh.html.jinja | 2 +- .../material/_base/module.html.jinja | 14 ++++++------- .../material/_base/signature.html.jinja | 2 +- .../material/_base/summary.html.jinja | 2 +- .../_base/summary/attributes.html.jinja | 2 +- .../material/_base/summary/classes.html.jinja | 2 +- .../_base/summary/functions.html.jinja | 2 +- .../material/_base/summary/modules.html.jinja | 2 +- .../_base/docstring/attributes.html.jinja | 2 +- .../docstring/other_parameters.html.jinja | 2 +- .../_base/docstring/parameters.html.jinja | 2 +- .../_base/docstring/raises.html.jinja | 2 +- .../_base/docstring/receives.html.jinja | 2 +- .../_base/docstring/returns.html.jinja | 2 +- .../_base/docstring/warns.html.jinja | 2 +- .../_base/docstring/yields.html.jinja | 2 +- .../readthedocs/_base/language.html.jinja | 2 +- 52 files changed, 100 insertions(+), 100 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ec519312..7cd3818a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -227,12 +227,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Release Insiders features of the $500/month funding goal ([bd30106](https://github.com/mkdocstrings/python/commit/bd301061fe9c647f9b91c2c9b4baa784c304eca7) by Timothée Mazzucotelli). The features and projects related to *mkdocstrings-python* are: - + - [Cross-references for type annotations in signatures](https://mkdocstrings.github.io/python/usage/configuration/signatures/#signature_crossrefs) - [Symbol types in headings and table of contents](https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc) - [`griffe-inherited-docstrings`](https://mkdocstrings.github.io/griffe-inherited-docstrings/), a Griffe extension for inheriting docstrings - [`griffe2md`](https://mkdocstrings.github.io/griffe2md/), a tool to output API docs to Markdown using Griffe - + See the complete list of features and projects here: https://pawamoy.github.io/insiders/#500-plasmavac-user-guide. @@ -464,7 +464,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. You can see how to use the filter in this commit's changes: [f686f4e4](https://github.com/mkdocstrings/python/commit/f686f4e4599cea64686d4ef4863b507dd096a513). - + **We take this as an opportunity to go out of beta and bump the version to 1.0.0. This will allow users to rely on semantic versioning.** diff --git a/docs/.glossary.md b/docs/.glossary.md index 917c95c4..e11a6781 100644 --- a/docs/.glossary.md +++ b/docs/.glossary.md @@ -6,7 +6,7 @@ [Griffe]: https://github.com/mkdocstrings/griffe [ReadTheDocs Sphinx theme]: https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html [Spacy's documentation]: https://spacy.io/api/doc/ -[Black]: https://pypi.org/project/black/ +[Black]: https://pypi.org/project/black/ [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material [Ruff]: https://docs.astral.sh/ruff diff --git a/docs/.overrides/main.html b/docs/.overrides/main.html index 1e956857..5bedfd03 100644 --- a/docs/.overrides/main.html +++ b/docs/.overrides/main.html @@ -1,13 +1,13 @@ {% extends "base.html" %} {% block announce %} - + Fund this project through sponsorship {% include ".icons/octicons/heart-fill-16.svg" %} — - + Follow @pawamoy on diff --git a/docs/.overrides/partials/comments.html b/docs/.overrides/partials/comments.html index 0dedc405..1d5c6051 100644 --- a/docs/.overrides/partials/comments.html +++ b/docs/.overrides/partials/comments.html @@ -31,7 +31,7 @@

Feedback

: "light" // Instruct Giscus to set theme - giscus.setAttribute("data-theme", theme) + giscus.setAttribute("data-theme", theme) } // Register event handlers after documented loaded diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 17a11ce4..288075b1 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -161,7 +161,7 @@ You can cancel your sponsorship anytime.[^5] 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: #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. @@ -221,7 +221,7 @@ by the [ISC License][license]. However, we kindly ask you to respect our - 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 + 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 diff --git a/docs/insiders/installation.md b/docs/insiders/installation.md index 0e4628ca..3588e691 100644 --- a/docs/insiders/installation.md +++ b/docs/insiders/installation.md @@ -42,21 +42,21 @@ Or using HTTPS: pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/mkdocstrings-python.git ``` ->? NOTE: **How to get a GitHub personal access token** +>? 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. diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index 461556bf..dd621735 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -274,7 +274,7 @@ plugins: ::: your_package.your_module options: preload_modules: - - their_package + - their_package ``` ```python title="your_package/your_module.py" diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index 467779e4..ef961ad4 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -286,15 +286,15 @@ More text. type: preview //// tab | With ToC entry -**Table of contents** -[Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" } -[`object`](#permalink-to-object){ title="#permalink-to-object" } -[Other heading](#permalink-to-other-heading){ title="#permalink-to-other-heading" } +**Table of contents** +[Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" } +[`object`](#permalink-to-object){ title="#permalink-to-object" } +[Other heading](#permalink-to-other-heading){ title="#permalink-to-other-heading" } //// //// tab | Without ToC entry -**Table of contents** -[Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" } +**Table of contents** +[Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" } [Other heading](#permalink-to-other-heading){ title="#permalink-to-other-heading" } //// /// @@ -400,7 +400,7 @@ plugins: Show the full Python path of every object. Same as for [`show_root_members_full_path`][], -but for every member, recursively. This option takes precedence over +but for every member, recursively. This option takes precedence over [`show_root_members_full_path`][]: `show_root_members_full_path` | `show_object_full_path` | Direct root members path @@ -454,7 +454,7 @@ When [grouped by categories][group_by_category], show a heading for each categor These category headings will appear in the table of contents, allowing you to link to them using their permalinks. -WARNING: **Not recommended with deeply nested object** +WARNING: **Not recommended with deeply nested objects.** When injecting documentation for deeply nested objects, you'll quickly run out of heading levels, and the objects at the bottom of the tree risk all getting documented diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index 879db6b1..345e1536 100644 --- a/docs/usage/configuration/signatures.md +++ b/docs/usage/configuration/signatures.md @@ -202,7 +202,7 @@ plugins: [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.8.0](../../insiders/changelog.md#1.8.0) — -**This feature also requires +**This feature also requires [Griffe Insiders](https://mkdocstrings.github.io/griffe/insiders/) to be installed.** diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 907809c8..9e13da66 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -371,9 +371,9 @@ Available context: #### Docstring sections In `docstring/attributes.html`, -`docstring/functions.html`, -`docstring/classes.html`, -`docstring/modules.html`, +`docstring/functions.html`, +`docstring/classes.html`, +`docstring/modules.html`, `docstring/other_parameters.html`, `docstring/parameters.html`, `docstring/raises.html`, diff --git a/docs/usage/docstrings/google.md b/docs/usage/docstrings/google.md index de35d46e..1c843a3b 100644 --- a/docs/usage/docstrings/google.md +++ b/docs/usage/docstrings/google.md @@ -17,11 +17,11 @@ For example: This admonition has a custom title! """ ``` - + === "Result" NOTE: It looks like a section, but it will be rendered as an admonition. - TIP: **You can even choose a title.** + TIP: **You can even choose a title.** This admonition has a custom title! See [Napoleon's documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). diff --git a/docs/usage/index.md b/docs/usage/index.md index 57b9fdc1..87f0a13f 100644 --- a/docs/usage/index.md +++ b/docs/usage/index.md @@ -1,6 +1,6 @@ # Usage -TIP: **This is the documentation for the NEW Python handler.** +TIP: **This is the documentation for the NEW Python handler.** To read the documentation for the LEGACY handler, go to the [legacy handler documentation](https://mkdocstrings.github.io/python-legacy). @@ -94,7 +94,7 @@ When importing an inventory, you enable automatic cross-references to other documentation sites like the standard library docs or any third-party package docs. Typically, you want to import the inventories of your project's dependencies, at least those -that are used in the public API. +that are used in the public API. See [*mkdocstrings*' documentation on inventories][inventories] for more details. @@ -292,7 +292,7 @@ to make sure anyone can build your docs from any location on their filesystem. ### Using the PYTHONPATH environment variable -WARNING: **This method has limitations.** +WARNING: **This method has limitations.** This method might work for you, with your current setup, but not for others trying your build your docs with their own setup/environment. We recommend using the [`paths` method](#using-the-paths-option) instead. @@ -348,10 +348,10 @@ In Bash and other shells, you can run your command like this ```bash PYTHONPATH=src mkdocs build -f docs/mkdocs.yml ``` - + ### Installing your package in the current Python environment -WARNING: **This method has limitations.** +WARNING: **This method has limitations.** This method might work for you, with your current setup, but not for others trying your build your docs with their own setup/environment. We recommend using the [`paths` method](#using-the-paths-option) instead. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index 7f3707b6..0ee0151a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja @@ -12,7 +12,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering " + attribute.path) }} @@ -44,7 +44,7 @@ Context: {% block heading scoped %} {#- Heading block. - + This block renders the heading for the attribute. -#} {% if config.show_symbol_type_heading %}{% endif %} @@ -60,7 +60,7 @@ Context: {% block labels scoped %} {#- Labels block. - + This block renders the labels for the attribute. -#} {% with labels = attribute.labels %} @@ -72,7 +72,7 @@ Context: {% block signature scoped %} {#- Signature block. - + This block renders the signature for the attribute. -#} {% if config.separate_signature %} @@ -99,14 +99,14 @@ Context:
{% block contents scoped %} {#- Contents block. - + This block renders the contents of the attribute. It contains other blocks that users can override. Overriding the contents block allows to rearrange the order of the blocks. -#} {% block docstring scoped %} {#- Docstring block. - + This block renders the docstring for the attribute. -#} {% with docstring_sections = attribute.docstring.parsed %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja index c9c23156..d8d7b87b 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja @@ -13,7 +13,7 @@ Context: {% if obj.all_members %} {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering children of " + obj.path) }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index ff5e51c9..11238337 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -11,7 +11,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering " + class.path) }} @@ -43,7 +43,7 @@ Context: {% block heading scoped %} {#- Heading block. - + This block renders the heading for the class. -#} {% if config.show_symbol_type_heading %}{% endif %} @@ -62,7 +62,7 @@ Context: {% block labels scoped %} {#- Labels block. - + This block renders the labels for the class. -#} {% with labels = class.labels %} @@ -74,7 +74,7 @@ Context: {% block signature scoped %} {#- Signature block. - + This block renders the signature for the class. Overloads of the `__init__` method are rendered if `merge_init_into_class` is enabled. The actual `__init__` method signature is only rendered if `separate_signature` is also enabled. @@ -117,14 +117,14 @@ Context:
{% block contents scoped %} {#- Contents block. - + This block renders the contents of the class. It contains other blocks that users can override. Overriding the contents block allows to rearrange the order of the blocks. -#} {% block bases scoped %} {#- Class bases block. - + This block renders the bases for the class. -#} {% if config.show_bases and class.bases %} @@ -138,7 +138,7 @@ Context: {% block docstring scoped %} {#- Docstring block. - + This block renders the docstring for the class. -#} {% with docstring_sections = class.docstring.parsed %} @@ -161,7 +161,7 @@ Context: {% block summary scoped %} {#- Summary block. - + This block renders auto-summaries for classes, methods, and attributes. -#} {% include "summary"|get_template with context %} @@ -169,7 +169,7 @@ Context: {% block source scoped %} {#- Source block. - + This block renders the source code for the class. -#} {% if config.show_source %} @@ -205,7 +205,7 @@ Context: {% block children scoped %} {#- Children block. - + This block renders the children (members) of the class. -#} {% set root = False %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja index 14d11d03..6983b2e1 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja @@ -14,7 +14,7 @@ Context: {% if docstring_sections %} {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering docstring") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja index ff6e9cbc..7f949130 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja @@ -8,7 +8,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering admonition") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja index 0bb416e0..13bd15b2 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering attributes section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja index 82bae98c..73f39329 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering classes section") }} 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 index 5a086497..0caacc15 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering examples section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja index f979f4e5..28bb0cae 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering functions section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja index b18e69f0..d55f854e 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering modules section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja index 24c6b194..1689dcb8 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering other parameters section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja index fef553b1..d4e9acb8 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering parameters section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja index f796494b..d734e94a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering raises section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja index 57df473f..3b618c66 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering receives section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja index cab2ca77..af61fce5 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering returns section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja index a892244a..782c0cdf 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering warns section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja index 96c373dd..6d3cfa14 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering yields section") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja index 4aea143d..5d7c07d5 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja @@ -6,14 +6,14 @@ which is a tree-like structure representing a Python expression. {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% endblock logs %} {%- macro crossref(name, annotation_path) -%} {#- Output a cross-reference. - + This macro outputs a cross-reference to the given name. Parameters: diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja index 973c762e..38323217 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja @@ -11,7 +11,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering " + function.path) }} @@ -49,7 +49,7 @@ Context: {% block heading scoped %} {#- Heading block. - + This block renders the heading for the function. -#} {% if config.show_symbol_type_heading %}{% endif %} @@ -64,7 +64,7 @@ Context: {% block labels scoped %} {#- Labels block. - + This block renders the labels for the function. -#} {% with labels = function.labels %} @@ -76,7 +76,7 @@ Context: {% block signature scoped %} {#- Signature block. - + This block renders the signature for the function, as well as its overloaded signatures if any. -#} @@ -114,14 +114,14 @@ Context:
{% block contents scoped %} {#- Contents block. - + This block renders the contents of the function. It contains other blocks that users can override. Overriding the contents block allows to rearrange the order of the blocks. -#} {% block docstring scoped %} {#- Docstring block. - + This block renders the docstring for the function. -#} {% with docstring_sections = function.docstring.parsed %} @@ -131,7 +131,7 @@ Context: {% block source scoped %} {#- Source block. - + This block renders the source code for the function. -#} {% if config.show_source and function.source %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja index dced4913..bbd3a7c1 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja @@ -12,7 +12,7 @@ Context: {% 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") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja index 5b643726..e3a614bb 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% 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 index d988b6ab..bcdcce2d 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% 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 index a6b7728b..76e59f2c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% 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 index f748b83c..1846960e 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja index 2085b95d..87463aa8 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja @@ -11,7 +11,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering " + module.path) }} @@ -43,7 +43,7 @@ Context: {% block heading scoped %} {#- Heading block. - + This block renders the heading for the module. -#} {% if config.show_symbol_type_heading %}{% endif %} @@ -56,7 +56,7 @@ Context: {% block labels scoped %} {#- Labels block. - + This block renders the labels for the module. -#} {% with labels = module.labels %} @@ -82,14 +82,14 @@ Context:
{% block contents scoped %} {#- Contents block. - + This block renders the contents of the module. It contains other blocks that users can override. Overriding the contents block allows to rearrange the order of the blocks. -#} {% block docstring scoped %} {#- Docstring block. - + This block renders the docstring for the module. -#} {% with docstring_sections = module.docstring.parsed %} @@ -99,7 +99,7 @@ Context: {% block summary scoped %} {#- Summary block. - + This block renders auto-summaries for classes, methods, and attributes. -#} {% include "summary"|get_template with context %} @@ -107,7 +107,7 @@ Context: {% block children scoped %} {#- Children block. - + This block renders the children (members) of the module. -#} {% set root = False %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja index 750cac30..eb8cf552 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja @@ -12,7 +12,7 @@ Context: {%- if config.show_signature -%} {%- block logs scoped -%} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug("Rendering signature") }} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja index 508e5660..0a4ee071 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja index 65b7c5b8..8bc8cb60 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/attributes.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja index b9792ada..1b1ef8f3 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/classes.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja index ad8b6f88..f03dfba2 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/functions.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja index 35d6e110..15e78088 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/modules.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% endblock logs %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja index 8df3f9f3..ad798971 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug() }} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja index 287bbf3d..beb4f678 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug() }} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja index da30d60a..295ab082 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug() }} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja index ffa3fad1..7fa8cd86 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug() }} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja index 40c77846..9ee189bc 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug() }} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja index 597d8932..2dbd21af 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug() }} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja index d66ac431..61f3c839 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug() }} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja index 4d4fc3d5..0fa6fcbc 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja @@ -9,7 +9,7 @@ Context: {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {{ log.debug() }} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja index 1465471d..21163f47 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/language.html.jinja @@ -2,7 +2,7 @@ {% block logs scoped %} {#- Logging block. - + This block can be used to log debug messages, deprecation messages, warnings, etc. -#} {% endblock logs %} From add00435a50ab29a67a1b7a1b908dae677ae0718 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 29 Jan 2025 15:05:56 +0100 Subject: [PATCH 022/100] style: Format --- scripts/insiders.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/insiders.py b/scripts/insiders.py index 849c6314..a7da99bc 100644 --- a/scripts/insiders.py +++ b/scripts/insiders.py @@ -26,7 +26,7 @@ def human_readable_amount(amount: int) -> str: # noqa: D103 str_amount = str(amount) if len(str_amount) >= 4: # noqa: PLR2004 - return f"{str_amount[:len(str_amount)-3]},{str_amount[-3:]}" + return f"{str_amount[: len(str_amount) - 3]},{str_amount[-3:]}" return str_amount From 7cabacf13735dbc5066793baf5820d61cd342dc8 Mon Sep 17 00:00:00 2001 From: Yann Van Crombrugge <59556820+vancromy@users.noreply.github.com> Date: Wed, 29 Jan 2025 17:08:16 +0100 Subject: [PATCH 023/100] feat: Add `heading` and `toc_label` options Issue-mkdocstrings-725: https://github.com/mkdocstrings/mkdocstrings/issues/725 PR-236: https://github.com/mkdocstrings/python/pull/236 --- docs/usage/configuration/headings.md | 33 +++++++++++++++++++ src/mkdocstrings_handlers/python/handler.py | 4 +++ .../material/_base/attribute.html.jinja | 4 +-- .../templates/material/_base/class.html.jinja | 4 +-- .../material/_base/function.html.jinja | 4 +-- .../material/_base/module.html.jinja | 6 ++-- 6 files changed, 46 insertions(+), 9 deletions(-) diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index ef961ad4..33062baf 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -57,6 +57,39 @@ plugins: //// /// +## `heading` + +- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }** + + +A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier `:::`). This will override the default heading generated by the plugin. + +WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object. + +```md title="in docs/some_page.md (local configuration)" +::: path.to.module + options: + heading: "My fancy module" +``` + +## `toc_label` + +- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }** + + +A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier `:::`). This will override the default label generated by the plugin. + +WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object. + +NOTE: **Use with/without `heading`.** If you use this option without specifying a custom `heading`, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for `heading` and `toc_label`, we leave the customization entirely up to you. + +```md title="in docs/some_page.md (local configuration)" +::: path.to.module + options: + heading: "My fancy module" + toc_label: "My fancy module" +``` + ## `parameter_headings` [:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index e57ae9e7..5725d566 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -107,6 +107,8 @@ class PythonHandler(BaseHandler): "show_inheritance_diagram": False, "show_submodules": False, "group_by_category": True, + "heading": "", + "toc_label": "", "heading_level": 2, "members_order": rendering.Order.alphabetical.value, "docstring_section_style": "table", @@ -143,6 +145,8 @@ class PythonHandler(BaseHandler): The modules must be listed as an array of strings. Default: `None`. Attributes: Headings options: + heading (str): A custom string to override the autogenerated heading of the root object. + toc_label (str): A custom string to override the autogenerated toc label of the root object. heading_level (int): The initial heading level to use. Default: `2`. parameter_headings (bool): Whether to render headings for parameters (therefore showing parameters in the ToC). Default: `False`. show_root_heading (bool): Show the heading of the object at the root of the documentation tree diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index 0ee0151a..c13bb641 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja @@ -49,7 +49,7 @@ Context: -#} {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} - {{ attribute_name }} + {{ config.heading if config.heading and root else attribute_name }} {% else %} {%+ filter highlight(language="python", inline=True) %} {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %} @@ -88,7 +88,7 @@ Context: {% filter heading(heading_level, role="data" if attribute.parent.kind.value == "module" else "attr", id=html_id, - toc_label=(' '|safe if config.show_symbol_type_toc else '') + attribute.name, + toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute_name), hidden=True, ) %} {% endfilter %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index 11238337..aefa98d1 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -48,7 +48,7 @@ Context: -#} {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} - {{ class_name }} + {{ config.heading if config.heading and root else class_name }} {% elif config.merge_init_into_class and "__init__" in all_members %} {% with function = all_members["__init__"] %} {%+ filter highlight(language="python", inline=True) %} @@ -106,7 +106,7 @@ Context: {% filter heading(heading_level, role="class", id=html_id, - toc_label=(' '|safe if config.show_symbol_type_toc else '') + class.name, + toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else class.name), hidden=True, ) %} {% endfilter %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja index 38323217..5e803ffb 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja @@ -54,7 +54,7 @@ Context: -#} {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} - {{ function_name }} + {{ config.heading if config.heading and root else function_name }} {% else %} {%+ filter highlight(language="python", inline=True) %} {{ function_name }}{% include "signature"|get_template with context %} @@ -103,7 +103,7 @@ Context: heading_level, role="function", id=html_id, - toc_label=((' ')|safe if config.show_symbol_type_toc else '') + function.name, + toc_label=((' ')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name), hidden=True, ) %} {% endfilter %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja index 87463aa8..fa2d2e6a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja @@ -38,7 +38,7 @@ Context: role="module", id=html_id, class="doc doc-heading", - toc_label=(' '|safe if config.show_symbol_type_toc else '') + module.name, + toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name), ) %} {% block heading scoped %} @@ -48,7 +48,7 @@ Context: -#} {% if config.show_symbol_type_heading %}{% endif %} {% if config.separate_signature %} - {{ module_name }} + {{ config.heading if config.heading and root else module_name }} {% else %} {{ module_name }} {% endif %} @@ -71,7 +71,7 @@ Context: {% filter heading(heading_level, role="module", id=html_id, - toc_label=(' '|safe if config.show_symbol_type_toc else '') + module.name, + toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name), hidden=True, ) %} {% endfilter %} From 7d608423a5103a4628f3ba06d6eca97541fd16e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 3 Feb 2025 17:07:13 +0100 Subject: [PATCH 024/100] ci: Ignore type warning about soup in test --- tests/test_end_to_end.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_end_to_end.py b/tests/test_end_to_end.py index 05dcfeb3..52340bc0 100644 --- a/tests/test_end_to_end.py +++ b/tests/test_end_to_end.py @@ -21,7 +21,7 @@ def _normalize_html(html: str) -> str: soup = bs4.BeautifulSoup(html, features="html.parser") - html = soup.prettify() + html = soup.prettify() # type: ignore[assignment] html = re.sub(r"\b(0x)[a-f0-9]+\b", r"\1...", html) html = re.sub(r"^(Build Date UTC ?:).+", r"\1...", html, flags=re.MULTILINE) html = re.sub(r"\b[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\b", r"...", html) From 5ebeda6fce1b1bc7cb3f5e27a5a90ac394a3de0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 13 Jan 2025 18:24:30 +0100 Subject: [PATCH 025/100] refactor: Use dataclasses for configuration/options and automate schema generation --- config/pytest.ini | 3 +- docs/schema.json | 316 ------ docs/usage/index.md | 7 - duties.py | 2 + mkdocs.yml | 5 + pyproject.toml | 5 +- scripts/griffe_extensions.py | 46 + scripts/mkdocs_hooks.py | 32 + src/mkdocstrings_handlers/python/config.py | 994 ++++++++++++++++++ src/mkdocstrings_handlers/python/handler.py | 409 +++---- src/mkdocstrings_handlers/python/rendering.py | 25 +- .../material/_base/children.html.jinja | 2 +- .../material/_base/summary/modules.html.jinja | 2 +- tests/helpers.py | 9 +- tests/test_end_to_end.py | 6 +- tests/test_handler.py | 60 +- tests/test_rendering.py | 16 +- tests/test_themes.py | 5 +- 18 files changed, 1265 insertions(+), 679 deletions(-) delete mode 100644 docs/schema.json create mode 100644 scripts/griffe_extensions.py create mode 100644 scripts/mkdocs_hooks.py create mode 100644 src/mkdocstrings_handlers/python/config.py diff --git a/config/pytest.ini b/config/pytest.ini index 25f9c92e..4f43c18e 100644 --- a/config/pytest.ini +++ b/config/pytest.ini @@ -10,6 +10,7 @@ testpaths = # action:message_regex:warning_class:module_regex:line filterwarnings = error - # TODO: remove once pytest-xdist 4 is released + # TODO: Remove once pytest-xdist 4 is released. ignore:.*rsyncdir:DeprecationWarning:xdist + # TODO: Remove once mkdocstrings stops setting fallback function. ignore:.*fallback anchor function:DeprecationWarning:mkdocstrings diff --git a/docs/schema.json b/docs/schema.json deleted file mode 100644 index e1863d26..00000000 --- a/docs/schema.json +++ /dev/null @@ -1,316 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft-07/schema", - "title": "Python handler for mkdocstrings.", - "type": "object", - "properties": { - "python": { - "markdownDescription": "https://mkdocstrings.github.io/python/", - "type": "object", - "properties": { - "import": { - "title": "Inventories to import.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#global-only-options", - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "object", - "properties": { - "url": { - "title": "URL of the inventory file.", - "type": "string" - }, - "base_url": { - "title": "Base URL used to build references URLs.", - "type": "string" - }, - "domains": { - "title": "Domains to import from the inventory.", - "description": "If not defined it will only import 'py' domain.", - "type": "array", - "items": { - "type": "string" - } - } - } - } - ] - } - }, - "paths": { - "title": "Local absolute/relative paths (relative to mkdocs.yml) to search packages into.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#paths", - "type": "array", - "items": { - "type": "string", - "format": "path" - } - }, - "load_external_modules": { - "title": "Load external modules to resolve aliases.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#load_external_modules", - "type": "boolean", - "default": false - }, - "options": { - "title": "Options for collecting and rendering objects.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "object", - "properties": { - "docstring_style": { - "title": "The docstring style to use when parsing docstrings.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_style", - "enum": [ - "google", - "numpy", - "sphinx" - ], - "default": "google" - }, - "docstring_options": { - "title": "The options for the docstring parser.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_options", - "default": null, - "items": { - "$ref": "https://raw.githubusercontent.com/mkdocstrings/griffe/master/docs/schema-docstrings-options.json" - } - }, - "show_root_heading": { - "title": "Show the heading of the object at the root of the documentation tree.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_heading", - "type": "boolean", - "default": false - }, - "show_root_toc_entry": { - "title": "If the root heading is not shown, at least add a ToC entry for it.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_toc_entry", - "type": "boolean", - "default": true - }, - "show_root_full_path": { - "title": "Show the full Python path for the root object heading.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_full_path", - "type": "boolean", - "default": true - }, - "show_root_members_full_path": { - "title": "Show the full Python path of the root members.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_root_members_full_path", - "type": "boolean", - "default": false - }, - "show_object_full_path": { - "title": "Show the full Python path of every object.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_object_full_path", - "type": "boolean", - "default": false - }, - "show_symbol_type_heading": { - "title": "Show the symbol type in headings (e.g. mod, class, func and attr).", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_heading", - "type": "boolean", - "default": false - }, - "show_symbol_type_toc": { - "title": "Show the symbol type in the Table of Contents (e.g. mod, class, func and attr).", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc", - "type": "boolean", - "default": false - }, - "show_category_heading": { - "title": "When grouped by categories, show a heading for each category.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_category_heading", - "type": "boolean", - "default": false - }, - "show_if_no_docstring": { - "title": "Show the object heading even if it has no docstring or children with docstrings.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_if_no_docstring", - "type": "boolean", - "default": false - }, - "show_signature": { - "title": "Show methods and functions signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#show_signature", - "type": "boolean", - "default": true - }, - "show_signature_annotations": { - "title": "Show the type annotations in methods and functions signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#show_signature_annotations", - "type": "boolean", - "default": false - }, - "separate_signature": { - "title": "Whether to put the whole signature in a code block below the heading. If a formatter (Black or Ruff) is installed, the signature is also formatted using it.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#separate_signature", - "type": "boolean", - "default": false - }, - "line_length": { - "title": "Maximum line length when formatting code/signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#line_length", - "type": "integer", - "default": 60 - }, - "merge_init_into_class": { - "title": "Whether to merge the `__init__` method into the class' signature and docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#merge_init_into_class", - "type": "boolean", - "default": false - }, - "show_docstring_attributes": { - "title": "Whether to display the \"Attributes\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_attributes", - "type": "boolean", - "default": true - }, - "show_docstring_description": { - "title": "Whether to display the textual block (including admonitions) in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_description", - "type": "boolean", - "default": true - }, - "show_docstring_examples": { - "title": "Whether to display the \"Examples\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_examples", - "type": "boolean", - "default": true - }, - "show_docstring_other_parameters": { - "title": "Whether to display the \"Other Parameters\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_other_parameters", - "type": "boolean", - "default": true - }, - "show_docstring_parameters": { - "title": "Whether to display the \"Parameters\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_parameters", - "type": "boolean", - "default": true - }, - "show_docstring_raises": { - "title": "Whether to display the \"Raises\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_raises", - "type": "boolean", - "default": true - }, - "show_docstring_receives": { - "title": "Whether to display the \"Receives\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_receives", - "type": "boolean", - "default": true - }, - "show_docstring_returns": { - "title": "Whether to display the \"Returns\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_returns", - "type": "boolean", - "default": true - }, - "show_docstring_warns": { - "title": "Whether to display the \"Warns\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_warns", - "type": "boolean", - "default": true - }, - "show_docstring_yields": { - "title": "Whether to display the \"Yields\" section in the object's docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_yields", - "type": "boolean", - "default": true - }, - "show_source": { - "title": "Show the source code of this object.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#show_source", - "type": "boolean", - "default": true - }, - "show_bases": { - "title": "Show the base classes of a class.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#show_bases", - "type": "boolean", - "default": true - }, - "show_submodules": { - "title": "When rendering a module, show its submodules recursively.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#show_submodules", - "type": "boolean", - "default": false - }, - "group_by_category": { - "title": "Group the object's children by categories: attributes, classes, functions, and modules.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#group_by_category", - "type": "boolean", - "default": true - }, - "heading_level": { - "title": "The initial heading level to use.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#heading_level", - "type": "integer", - "default": 2 - }, - "members_order": { - "title": "The members ordering to use.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#members_order", - "enum": [ - "alphabetical", - "source" - ], - "default": "alphabetical" - }, - "docstring_section_style": { - "title": "The style used to render docstring sections.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_section_style", - "enum": [ - "list", - "spacy", - "table" - ], - "default": "table" - }, - "members": { - "title": "An explicit list of members to render.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#members", - "type": [ - "boolean", - "array" - ], - "default": null - }, - "filters": { - "title": "A list of filters applied to filter objects based on their name. A filter starting with `!` will exclude matching objects instead of including them. The `members` option takes precedence over `filters` (filters will still be applied recursively to lower members in the hierarchy).", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/members/#filters", - "type": "array", - "default": [ - "!^_[^_]" - ] - }, - "annotations_path": { - "title": "The verbosity for annotations path.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/signatures/#annotations_path", - "enum": [ - "brief", - "source" - ], - "default": "brief" - }, - "preload_modules": { - "title": "Pre-load modules. It permits to resolve aliases pointing to these modules (packages), and therefore render members of an object that are external to the given object (originating from another package).", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/general/#preload_modules", - "type": "array", - "items": { - "type": "string" - } - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false -} \ No newline at end of file diff --git a/docs/usage/index.md b/docs/usage/index.md index 87f0a13f..8caafb48 100644 --- a/docs/usage/index.md +++ b/docs/usage/index.md @@ -199,13 +199,6 @@ in the following pages: - [Docstrings options](configuration/docstrings.md): options related to docstrings (parsing and rendering) - [Signature options](configuration/signatures.md): options related to signatures and type annotations -#### Options summary - -::: mkdocstrings_handlers.python.handler.PythonHandler.default_config - options: - show_root_heading: false - show_root_toc_entry: false - ## Finding modules There are multiple ways to tell the handler where to find your packages/modules. diff --git a/duties.py b/duties.py index bd051334..9e516ce5 100644 --- a/duties.py +++ b/duties.py @@ -88,6 +88,8 @@ def check_types(ctx: Context) -> None: ctx.run( tools.mypy(*PY_SRC_LIST, config_file="config/mypy.ini"), title=pyprefix("Type-checking"), + # TODO: Update when Pydantic supports 3.14. + nofail=sys.version_info >= (3, 14), ) diff --git a/mkdocs.yml b/mkdocs.yml index 2d546126..396f738f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,9 @@ validation: absolute_links: warn unrecognized_links: warn +hooks: +- scripts/mkdocs_hooks.py + nav: - Home: - Overview: index.md @@ -160,6 +163,8 @@ plugins: docstring_options: ignore_init_summary: true docstring_section_style: list + extensions: + - scripts/griffe_extensions.py filters: ["!^_"] heading_level: 1 inherited_members: true diff --git a/pyproject.toml b/pyproject.toml index c6f3cc50..b4a453e4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,9 +30,10 @@ classifiers = [ "Typing :: Typed", ] dependencies = [ - "mkdocstrings>=0.26", + "mkdocstrings>=0.28", "mkdocs-autorefs>=1.2", "griffe>=0.49", + "typing-extensions>=4.0; python_version < '3.11'", ] [project.urls] @@ -106,6 +107,7 @@ dev = [ "mkdocs-git-revision-date-localized-plugin>=1.2", "mkdocs-literate-nav>=0.6", "mkdocs-material>=9.5", + "pydantic>=2.10", "mkdocs-minify-plugin>=0.8", # YORE: EOL 3.10: Remove line. "tomli>=2.0; python_version < '3.11'", @@ -113,3 +115,4 @@ dev = [ [tool.inline-snapshot] storage-dir = "tests/snapshots" +format-command = "ruff format --config config/ruff.toml --stdin-filename {filename}" diff --git a/scripts/griffe_extensions.py b/scripts/griffe_extensions.py new file mode 100644 index 00000000..4ff0c8cc --- /dev/null +++ b/scripts/griffe_extensions.py @@ -0,0 +1,46 @@ +"""Custom extensions for Griffe.""" + +from __future__ import annotations + +import ast +from typing import Any + +import griffe + +logger = griffe.get_logger("griffe_extensions") + + +class CustomFields(griffe.Extension): + """Support our custom dataclass fields.""" + + def on_attribute_instance( + self, + *, + attr: griffe.Attribute, + agent: griffe.Visitor | griffe.Inspector, + **kwargs: Any, # noqa: ARG002 + ) -> None: + """Fetch descriptions from `Field` annotations.""" + if attr.docstring: + return + try: + field: griffe.ExprCall = attr.annotation.slice.elements[1] # type: ignore[union-attr] + except AttributeError: + return + + if field.canonical_path == "mkdocstrings_handler.python.config.Field": + description = next( + attr.value + for attr in field.arguments + if isinstance(attr, griffe.ExprKeyword) and attr.name == "description" + ) + if not isinstance(description, str): + logger.warning(f"Field description of {attr.path} is not a static string") + description = str(description) + + attr.docstring = griffe.Docstring( + ast.literal_eval(description), + parent=attr, + parser=agent.docstring_parser, + parser_options=agent.docstring_options, + ) diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py new file mode 100644 index 00000000..63e7578e --- /dev/null +++ b/scripts/mkdocs_hooks.py @@ -0,0 +1,32 @@ +"""Generate a JSON schema of the Python handler configuration.""" + +import json +from os.path import join +from typing import Any + +from mkdocs.config.defaults import MkDocsConfig +from mkdocs.plugins import get_plugin_logger + +from mkdocstrings_handlers.python.config import PythonInputConfig + +# TODO: Update when Pydantic supports Python 3.14 (sources and duties as well). +try: + from pydantic import TypeAdapter +except ImportError: + TypeAdapter = None # type: ignore[assignment,misc] + + +logger = get_plugin_logger(__name__) + + +def on_post_build(config: MkDocsConfig, **kwargs: Any) -> None: # noqa: ARG001 + """Write `schema.json` to the site directory.""" + if TypeAdapter is None: + logger.info("Pydantic is not installed, skipping JSON schema generation") + return + adapter = TypeAdapter(PythonInputConfig) + schema = adapter.json_schema() + schema["$schema"] = "https://json-schema.org/draft-07/schema" + with open(join(config.site_dir, "schema.json"), "w") as file: + json.dump(schema, file, indent=2) + logger.debug("Generated JSON schema") diff --git a/src/mkdocstrings_handlers/python/config.py b/src/mkdocstrings_handlers/python/config.py new file mode 100644 index 00000000..07f34397 --- /dev/null +++ b/src/mkdocstrings_handlers/python/config.py @@ -0,0 +1,994 @@ +"""Configuration and options dataclasses.""" + +from __future__ import annotations + +import re +import sys +from dataclasses import field, fields +from typing import TYPE_CHECKING, Annotated, Any, Literal + +# YORE: EOL 3.10: Replace block with line 2. +if sys.version_info >= (3, 11): + from typing import Self +else: + from typing_extensions import Self + +try: + # When Pydantic is available, use it to validate options (done automatically). + # Users can therefore opt into validation by installing Pydantic in development/CI. + # When building the docs to deploy them, Pydantic is not required anymore. + + # When building our own docs, Pydantic is always installed (see `docs` group in `pyproject.toml`) + # to allow automatic generation of a JSON Schema. The JSON Schema is then referenced by mkdocstrings, + # which is itself referenced by mkdocs-material's schema system. For example in VSCode: + # + # "yaml.schemas": { + # "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" + # } + from inspect import cleandoc + + from pydantic import Field as BaseField + from pydantic.dataclasses import dataclass + + _base_url = "https://mkdocstrings.github.io/python/usage" + + def Field( # noqa: N802, D103 + *args: Any, + description: str, + group: Literal["general", "headings", "members", "docstrings", "signatures"] | None = None, + parent: str | None = None, + **kwargs: Any, + ) -> None: + def _add_markdown_description(schema: dict[str, Any]) -> None: + url = f"{_base_url}/{f'configuration/{group}/' if group else ''}#{parent or schema['title']}" + schema["markdownDescription"] = f"[DOCUMENTATION]({url})\n\n{schema['description']}" + + return BaseField( + *args, + description=cleandoc(description), + field_title_generator=lambda name, _: name, + json_schema_extra=_add_markdown_description, + **kwargs, + ) +except ImportError: + from dataclasses import dataclass # type: ignore[no-redef] + + def Field(*args: Any, **kwargs: Any) -> None: # type: ignore[misc] # noqa: D103, N802 + pass + + +if TYPE_CHECKING: + from collections.abc import MutableMapping + + +# YORE: EOL 3.9: Remove block. +_dataclass_options = {"frozen": True} +if sys.version_info >= (3, 10): + _dataclass_options["kw_only"] = True + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class GoogleStyleOptions: + """Google style docstring options.""" + + ignore_init_summary: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="Whether to ignore the summary in `__init__` methods' docstrings.", + ), + ] = False + + returns_multiple_items: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="""Whether to parse multiple items in `Yields` and `Returns` sections. + + When true, each item's continuation lines must be indented. + When false (single item), no further indentation is required. + """, + ), + ] = True + + returns_named_value: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="""Whether to parse `Yields` and `Returns` section items as name and description, rather than type and description. + + When true, type must be wrapped in parentheses: `(int): Description.`. Names are optional: `name (int): Description.`. + When false, parentheses are optional but the items cannot be named: `int: Description`. + """, + ), + ] = True + + returns_type_in_property_summary: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="Whether to parse the return type of properties at the beginning of their summary: `str: Summary of the property`.", + ), + ] = False + + receives_multiple_items: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="""Whether to parse multiple items in `Receives` sections. + + When true, each item's continuation lines must be indented. + When false (single item), no further indentation is required. + """, + ), + ] = True + + receives_named_value: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="""Whether to parse `Receives` section items as name and description, rather than type and description. + + When true, type must be wrapped in parentheses: `(int): Description.`. Names are optional: `name (int): Description.`. + When false, parentheses are optional but the items cannot be named: `int: Description`. + """, + ), + ] = True + + trim_doctest_flags: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="Whether to remove doctest flags from Python example blocks.", + ), + ] = True + + warn_unknown_params: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="Warn about documented parameters not appearing in the signature.", + ), + ] = True + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class NumpyStyleOptions: + """Numpy style docstring options.""" + + ignore_init_summary: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="Whether to ignore the summary in `__init__` methods' docstrings.", + ), + ] = False + + trim_doctest_flags: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="Whether to remove doctest flags from Python example blocks.", + ), + ] = True + + warn_unknown_params: Annotated[ + bool, + Field( + group="docstrings", + parent="docstring_options", + description="Warn about documented parameters not appearing in the signature.", + ), + ] = True + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class SphinxStyleOptions: + """Sphinx style docstring options.""" + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class PerStyleOptions: + """Per style options.""" + + google: Annotated[ + GoogleStyleOptions, + Field( + group="docstrings", + parent="docstring_options", + description="Google-style options.", + ), + ] = field(default_factory=GoogleStyleOptions) + + numpy: Annotated[ + NumpyStyleOptions, + Field( + group="docstrings", + parent="docstring_options", + description="Numpydoc-style options.", + ), + ] = field(default_factory=NumpyStyleOptions) + + sphinx: Annotated[ + SphinxStyleOptions, + Field( + group="docstrings", + parent="docstring_options", + description="Sphinx-style options.", + ), + ] = field(default_factory=SphinxStyleOptions) + + @classmethod + def from_data(cls, **data: Any) -> Self: + """Create an instance from a dictionary.""" + if "google" in data: + data["google"] = GoogleStyleOptions(**data["google"]) + if "numpy" in data: + data["numpy"] = NumpyStyleOptions(**data["numpy"]) + if "sphinx" in data: + data["sphinx"] = SphinxStyleOptions(**data["sphinx"]) + return cls(**data) + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class AutoStyleOptions: + """Auto style docstring options.""" + + method: Annotated[ + Literal["heuristics", "max_sections"], + Field( + group="docstrings", + parent="docstring_options", + description="The method to use to determine the docstring style.", + ), + ] = "heuristics" + + style_order: Annotated[ + list[str], + Field( + group="docstrings", + parent="docstring_options", + description="The order of the docstring styles to try.", + ), + ] = field(default_factory=lambda: ["sphinx", "google", "numpy"]) + + default: Annotated[ + str | None, + Field( + group="docstrings", + parent="docstring_options", + description="The default docstring style to use if no other style is detected.", + ), + ] = None + + per_style_options: Annotated[ + PerStyleOptions, + Field( + group="docstrings", + parent="docstring_options", + description="Per-style options.", + ), + ] = field(default_factory=PerStyleOptions) + + @classmethod + def from_data(cls, **data: Any) -> Self: + """Create an instance from a dictionary.""" + if "per_style_options" in data: + data["per_style_options"] = PerStyleOptions.from_data(**data["per_style_options"]) + return cls(**data) + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class SummaryOption: + """Summary option.""" + + attributes: Annotated[ + bool, + Field( + group="members", + parent="summary", + description="Whether to render summaries of attributes.", + ), + ] = False + + functions: Annotated[ + bool, + Field( + group="members", + parent="summary", + description="Whether to render summaries of functions (methods).", + ), + ] = False + + classes: Annotated[ + bool, + Field( + group="members", + parent="summary", + description="Whether to render summaries of classes.", + ), + ] = False + + modules: Annotated[ + bool, + Field( + group="members", + parent="summary", + description="Whether to render summaries of modules.", + ), + ] = False + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class PythonInputOptions: + """Accepted input options.""" + + allow_inspection: Annotated[ + bool, + Field( + group="general", + description="Whether to allow inspecting modules when visiting them is not possible.", + ), + ] = True + + force_inspection: Annotated[ + bool, + Field( + group="general", + description="Whether to force using dynamic analysis when loading data.", + ), + ] = False + + annotations_path: Annotated[ + Literal["brief", "source", "full"], + Field( + group="signatures", + description="The verbosity for annotations path: `brief` (recommended), `source` (as written in the source), or `full`.", + ), + ] = "brief" + + docstring_options: Annotated[ + GoogleStyleOptions | NumpyStyleOptions | SphinxStyleOptions | AutoStyleOptions | None, + Field( + group="docstrings", + description="""The options for the docstring parser. + + See [docstring parsers](https://mkdocstrings.github.io/griffe/reference/docstrings/) and their options in Griffe docs. + """, + ), + ] = None + + docstring_section_style: Annotated[ + Literal["table", "list", "spacy"], + Field( + group="docstrings", + description="The style used to render docstring sections.", + ), + ] = "table" + + docstring_style: Annotated[ + Literal["auto", "google", "numpy", "sphinx"] | None, + Field( + group="docstrings", + description="The docstring style to use: `auto`, `google`, `numpy`, `sphinx`, or `None`.", + ), + ] = "google" + + extensions: Annotated[ + list[str | dict[str, Any]], + Field( + group="general", + description="A list of Griffe extensions to load.", + ), + ] = field(default_factory=list) + + filters: Annotated[ + list[str], + Field( + group="members", + description="""A list of filters applied to filter objects based on their name. + + A filter starting with `!` will exclude matching objects instead of including them. + The `members` option takes precedence over `filters` (filters will still be applied recursively + to lower members in the hierarchy). + """, + ), + ] = field(default_factory=lambda: ["!^_[^_]"]) + + find_stubs_package: Annotated[ + bool, + Field( + group="general", + description="Whether to load stubs package (package-stubs) when extracting docstrings.", + ), + ] = False + + group_by_category: Annotated[ + bool, + Field( + group="members", + description="Group the object's children by categories: attributes, classes, functions, and modules.", + ), + ] = True + + heading: Annotated[ + str, + Field( + group="headings", + description="A custom string to override the autogenerated heading of the root object.", + ), + ] = "" + + heading_level: Annotated[ + int, + Field( + group="headings", + description="The initial heading level to use.", + ), + ] = 2 + + inherited_members: Annotated[ + bool | list[str], + Field( + group="members", + description="""A boolean, or an explicit list of inherited members to render. + + If true, select all inherited members, which can then be filtered with `members`. + If false or empty list, do not select any inherited member. + """, + ), + ] = False + + line_length: Annotated[ + int, + Field( + group="signatures", + description="Maximum line length when formatting code/signatures.", + ), + ] = 60 + + members: Annotated[ + list[str] | bool | None, + Field( + group="members", + description="""A boolean, or an explicit list of members to render. + + If true, select all members without further filtering. + If false or empty list, do not render members. + If none, select all members and apply further filtering with filters and docstrings. + """, + ), + ] = None + + members_order: Annotated[ + Literal["alphabetical", "source"], + Field( + group="members", + description="""The members ordering to use. + + - `alphabetical`: order by the members names, + - `source`: order members as they appear in the source file. + """, + ), + ] = "alphabetical" + + merge_init_into_class: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to merge the `__init__` method into the class' signature and docstring.", + ), + ] = False + + modernize_annotations: Annotated[ + bool, + Field( + group="signatures", + description="Whether to modernize annotations, for example `Optional[str]` into `str | None`.", + ), + ] = False + + parameter_headings: Annotated[ + bool, + Field( + group="headings", + description="Whether to render headings for parameters (therefore showing parameters in the ToC).", + ), + ] = False + + preload_modules: Annotated[ + list[str], + Field( + group="general", + description="""Pre-load modules that are not specified directly in autodoc instructions (`::: identifier`). + + It is useful when you want to render documentation for a particular member of an object, + and this member is imported from another package than its parent. + + For an imported member to be rendered, you need to add it to the `__all__` attribute + of the importing module. + + The modules must be listed as an array of strings. + """, + ), + ] = field(default_factory=list) + + relative_crossrefs: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to enable the relative crossref syntax.", + ), + ] = False + + scoped_crossrefs: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to enable the scoped crossref ability.", + ), + ] = False + + separate_signature: Annotated[ + bool, + Field( + group="signatures", + description="""Whether to put the whole signature in a code block below the heading. + + If Black or Ruff are installed, the signature is also formatted using them. + """, + ), + ] = False + + show_bases: Annotated[ + bool, + Field( + group="general", + description="Show the base classes of a class.", + ), + ] = True + + show_category_heading: Annotated[ + bool, + Field( + group="headings", + description="When grouped by categories, show a heading for each category.", + ), + ] = False + + show_docstring_attributes: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Attributes' section in the object's docstring.", + ), + ] = True + + show_docstring_classes: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Classes' section in the object's docstring.", + ), + ] = True + + show_docstring_description: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the textual block (including admonitions) in the object's docstring.", + ), + ] = True + + show_docstring_examples: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Examples' section in the object's docstring.", + ), + ] = True + + show_docstring_functions: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Functions' or 'Methods' sections in the object's docstring.", + ), + ] = True + + show_docstring_modules: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Modules' section in the object's docstring.", + ), + ] = True + + show_docstring_other_parameters: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Other Parameters' section in the object's docstring.", + ), + ] = True + + show_docstring_parameters: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Parameters' section in the object's docstring.", + ), + ] = True + + show_docstring_raises: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Raises' section in the object's docstring.", + ), + ] = True + + show_docstring_receives: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Receives' section in the object's docstring.", + ), + ] = True + + show_docstring_returns: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Returns' section in the object's docstring.", + ), + ] = True + + show_docstring_warns: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Warns' section in the object's docstring.", + ), + ] = True + + show_docstring_yields: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to display the 'Yields' section in the object's docstring.", + ), + ] = True + + show_if_no_docstring: Annotated[ + bool, + Field( + group="docstrings", + description="Show the object heading even if it has no docstring or children with docstrings.", + ), + ] = False + + show_inheritance_diagram: Annotated[ + bool, + Field( + group="docstrings", + description="Show the inheritance diagram of a class using Mermaid.", + ), + ] = False + + show_labels: Annotated[ + bool, + Field( + group="docstrings", + description="Whether to show labels of the members.", + ), + ] = True + + show_object_full_path: Annotated[ + bool, + Field( + group="docstrings", + description="Show the full Python path of every object.", + ), + ] = False + + show_root_full_path: Annotated[ + bool, + Field( + group="docstrings", + description="Show the full Python path for the root object heading.", + ), + ] = True + + show_root_heading: Annotated[ + bool, + Field( + group="headings", + description="""Show the heading of the object at the root of the documentation tree. + + The root object is the object referenced by the identifier after `:::`. + """, + ), + ] = False + + show_root_members_full_path: Annotated[ + bool, + Field( + group="headings", + description="Show the full Python path of the root members.", + ), + ] = False + + show_root_toc_entry: Annotated[ + bool, + Field( + group="headings", + description="If the root heading is not shown, at least add a ToC entry for it.", + ), + ] = True + + show_signature_annotations: Annotated[ + bool, + Field( + group="signatures", + description="Show the type annotations in methods and functions signatures.", + ), + ] = False + + show_signature: Annotated[ + bool, + Field( + group="signatures", + description="Show methods and functions signatures.", + ), + ] = True + + show_source: Annotated[ + bool, + Field( + group="general", + description="Show the source code of this object.", + ), + ] = True + + show_submodules: Annotated[ + bool, + Field( + group="members", + description="When rendering a module, show its submodules recursively.", + ), + ] = False + + show_symbol_type_heading: Annotated[ + bool, + Field( + group="headings", + description="Show the symbol type in headings (e.g. mod, class, meth, func and attr).", + ), + ] = False + + show_symbol_type_toc: Annotated[ + bool, + Field( + group="headings", + description="Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).", + ), + ] = False + + signature_crossrefs: Annotated[ + bool, + Field( + group="signatures", + description="Whether to render cross-references for type annotations in signatures.", + ), + ] = False + + summary: Annotated[ + bool | SummaryOption, + Field( + group="members", + description="Whether to render summaries of modules, classes, functions (methods) and attributes.", + ), + ] = field(default_factory=SummaryOption) + + toc_label: Annotated[ + str, + Field( + group="headings", + description="A custom string to override the autogenerated toc label of the root object.", + ), + ] = "" + + unwrap_annotated: Annotated[ + bool, + Field( + group="signatures", + description="Whether to unwrap `Annotated` types to show only the type without the annotations.", + ), + ] = False + + extra: Annotated[ + dict[str, Any], + Field( + group="general", + description="Extra options.", + ), + ] = field(default_factory=dict) + + @classmethod + def _extract_extra(cls, data: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]: + field_names = {field.name for field in fields(cls)} + copy = data.copy() + return {name: copy.pop(name) for name in data if name not in field_names}, copy + + # YORE: Bump 2: Remove block. + def __init__(self, **kwargs: Any) -> None: + """Initialize the instance.""" + extra_fields = self._extract_extra(kwargs) + for name, value in kwargs.items(): + object.__setattr__(self, name, value) + if extra_fields: + object.__setattr__(self, "_extra", extra_fields) + + @classmethod + def coerce(cls, **data: Any) -> MutableMapping[str, Any]: + """Coerce data.""" + if "docstring_options" in data: + docstring_style = data.get("docstring_style", "google") + docstring_options = data["docstring_options"] + if docstring_options is not None: + if docstring_style == "auto": + docstring_options = AutoStyleOptions.from_data(**docstring_options) + elif docstring_style == "google": + docstring_options = GoogleStyleOptions(**docstring_options) + elif docstring_style == "numpy": + docstring_options = NumpyStyleOptions(**docstring_options) + elif docstring_style == "sphinx": + docstring_options = SphinxStyleOptions(**docstring_options) + data["docstring_options"] = docstring_options + if "summary" in data: + summary = data["summary"] + if summary is True: + summary = SummaryOption(attributes=True, functions=True, classes=True, modules=True) + elif summary is False: + summary = SummaryOption(attributes=False, functions=False, classes=False, modules=False) + else: + summary = SummaryOption(**summary) + data["summary"] = summary + return data + + @classmethod + def from_data(cls, **data: Any) -> Self: + """Create an instance from a dictionary.""" + return cls(**cls.coerce(**data)) + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class PythonOptions(PythonInputOptions): # type: ignore[override,unused-ignore] + """Final options passed as template context.""" + + filters: list[tuple[re.Pattern, bool]] = field(default_factory=list) # type: ignore[assignment] + """A list of filters applied to filter objects based on their name.""" + + summary: SummaryOption = field(default_factory=SummaryOption) + """Whether to render summaries of modules, classes, functions (methods) and attributes.""" + + @classmethod + def coerce(cls, **data: Any) -> MutableMapping[str, Any]: + """Create an instance from a dictionary.""" + if "filters" in data: + data["filters"] = [ + (re.compile(filtr.lstrip("!")), filtr.startswith("!")) for filtr in data["filters"] or () + ] + return super().coerce(**data) + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class Inventory: + """An inventory.""" + + url: Annotated[ + str, + Field( + parent="inventories", + description="The URL of the inventory.", + ), + ] + + base: Annotated[ + str | None, + Field( + parent="inventories", + description="The base URL of the inventory.", + ), + ] = None + + domains: Annotated[ + list[str], + Field( + parent="inventories", + description="The domains to load from the inventory.", + ), + ] = field(default_factory=lambda: ["py"]) + + @property + def _config(self) -> dict[str, Any]: + return {"base": self.base, "domains": self.domains} + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class PythonInputConfig: + """Python handler configuration.""" + + inventories: Annotated[ + list[str | Inventory], + Field(description="The inventories to load."), + ] = field(default_factory=list) + + paths: Annotated[ + list[str], + Field(description="The paths in which to search for Python packages."), + ] = field(default_factory=lambda: ["."]) + + load_external_modules: Annotated[ + bool | None, + Field(description="Whether to always load external modules/packages."), + ] = None + + options: Annotated[ + PythonInputOptions, + Field(description="Configuration options for collecting and rendering objects."), + ] = field(default_factory=PythonInputOptions) + + locale: Annotated[ + str | None, + Field(description="The locale to use when translating template strings."), + ] = None + + @classmethod + def coerce(cls, **data: Any) -> MutableMapping[str, Any]: + """Coerce data.""" + return data + + @classmethod + def from_data(cls, **data: Any) -> Self: + """Create an instance from a dictionary.""" + return cls(**cls.coerce(**data)) + + +# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line. +@dataclass(**_dataclass_options) # type: ignore[call-overload] +class PythonConfig(PythonInputConfig): # type: ignore[override,unused-ignore] + """Python handler configuration.""" + + inventories: list[Inventory] = field(default_factory=list) # type: ignore[assignment] + options: dict[str, Any] = field(default_factory=dict) # type: ignore[assignment] + + @classmethod + def coerce(cls, **data: Any) -> MutableMapping[str, Any]: + """Coerce data.""" + if "inventories" in data: + data["inventories"] = [ + Inventory(url=inv) if isinstance(inv, str) else Inventory(**inv) for inv in data["inventories"] + ] + return data diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 5725d566..bf22876d 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -5,12 +5,12 @@ import glob import os import posixpath -import re import sys -from collections import ChainMap from contextlib import suppress +from dataclasses import asdict from pathlib import Path from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar +from warnings import warn from griffe import ( AliasResolutionError, @@ -21,17 +21,18 @@ load_extensions, patch_loggers, ) -from mkdocstrings.extension import PluginError -from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem +from mkdocs.exceptions import PluginError +from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem, HandlerOptions from mkdocstrings.inventory import Inventory from mkdocstrings.loggers import get_logger from mkdocstrings_handlers.python import rendering +from mkdocstrings_handlers.python.config import PythonConfig, PythonOptions if TYPE_CHECKING: - from collections.abc import Iterator, Mapping, Sequence + from collections.abc import Iterator, Mapping, MutableMapping, Sequence - from markdown import Markdown + from mkdocs.config.defaults import MkDocsConfig if sys.version_info >= (3, 11): @@ -55,215 +56,78 @@ def chdir(path: str) -> Iterator[None]: # noqa: D103 patch_loggers(get_logger) +def _warn_extra_options(names: Sequence[str]) -> None: + warn( + "Passing extra options directly under `options` is deprecated. " + "Instead, pass them under `options.extra`, and update your templates. " + f"Current extra (unrecognized) options: {', '.join(sorted(names))}", + DeprecationWarning, + stacklevel=3, + ) + + class PythonHandler(BaseHandler): """The Python handler class.""" - name: str = "python" + name: ClassVar[str] = "python" """The handler's name.""" - domain: str = "py" # to match Sphinx's default domain + + domain: ClassVar[str] = "py" """The cross-documentation domain/language for this handler.""" - enable_inventory: bool = True + + enable_inventory: ClassVar[bool] = True """Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file.""" - fallback_theme = "material" + + fallback_theme: ClassVar[str] = "material" """The fallback theme.""" - fallback_config: ClassVar[dict] = {"fallback": True} - """The configuration used to collect item during autorefs fallback.""" - default_config: ClassVar[dict] = { - "find_stubs_package": False, - "docstring_style": "google", - "docstring_options": {}, - "show_symbol_type_heading": False, - "show_symbol_type_toc": False, - "show_root_heading": False, - "show_root_toc_entry": True, - "show_root_full_path": True, - "show_root_members_full_path": False, - "show_object_full_path": False, - "show_category_heading": False, - "show_if_no_docstring": False, - "show_signature": True, - "show_signature_annotations": False, - "signature_crossrefs": False, - "separate_signature": False, - "line_length": 60, - "merge_init_into_class": False, - "relative_crossrefs": False, - "scoped_crossrefs": False, - "show_docstring_attributes": True, - "show_docstring_functions": True, - "show_docstring_classes": True, - "show_docstring_modules": True, - "show_docstring_description": True, - "show_docstring_examples": True, - "show_docstring_other_parameters": True, - "show_docstring_parameters": True, - "show_docstring_raises": True, - "show_docstring_receives": True, - "show_docstring_returns": True, - "show_docstring_warns": True, - "show_docstring_yields": True, - "show_source": True, - "show_bases": True, - "show_inheritance_diagram": False, - "show_submodules": False, - "group_by_category": True, - "heading": "", - "toc_label": "", - "heading_level": 2, - "members_order": rendering.Order.alphabetical.value, - "docstring_section_style": "table", - "members": None, - "inherited_members": False, - "filters": ["!^_[^_]"], - "annotations_path": "brief", - "preload_modules": None, - "allow_inspection": True, - "force_inspection": False, - "summary": False, - "show_labels": True, - "unwrap_annotated": False, - "parameter_headings": False, - "modernize_annotations": False, - } - """Default handler configuration. - - Attributes: General options: - find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings. Default `False`. - allow_inspection (bool): Whether to allow inspecting modules when visiting them is not possible. Default: `True`. - force_inspection (bool): Whether to force using dynamic analysis when loading data. Default: `False`. - show_bases (bool): Show the base classes of a class. Default: `True`. - show_inheritance_diagram (bool): Show the inheritance diagram of a class using Mermaid. Default: `False`. - show_source (bool): Show the source code of this object. Default: `True`. - preload_modules (list[str] | None): Pre-load modules that are - not specified directly in autodoc instructions (`::: identifier`). - It is useful when you want to render documentation for a particular member of an object, - and this member is imported from another package than its parent. - - For an imported member to be rendered, you need to add it to the `__all__` attribute - of the importing module. - - The modules must be listed as an array of strings. Default: `None`. - - Attributes: Headings options: - heading (str): A custom string to override the autogenerated heading of the root object. - toc_label (str): A custom string to override the autogenerated toc label of the root object. - heading_level (int): The initial heading level to use. Default: `2`. - parameter_headings (bool): Whether to render headings for parameters (therefore showing parameters in the ToC). Default: `False`. - show_root_heading (bool): Show the heading of the object at the root of the documentation tree - (i.e. the object referenced by the identifier after `:::`). Default: `False`. - show_root_toc_entry (bool): If the root heading is not shown, at least add a ToC entry for it. Default: `True`. - show_root_full_path (bool): Show the full Python path for the root object heading. Default: `True`. - show_root_members_full_path (bool): Show the full Python path of the root members. Default: `False`. - show_object_full_path (bool): Show the full Python path of every object. Default: `False`. - show_category_heading (bool): When grouped by categories, show a heading for each category. Default: `False`. - show_symbol_type_heading (bool): Show the symbol type in headings (e.g. mod, class, meth, func and attr). Default: `False`. - show_symbol_type_toc (bool): Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr). Default: `False`. - - Attributes: Members options: - inherited_members (list[str] | bool | None): A boolean, or an explicit list of inherited members to render. - If true, select all inherited members, which can then be filtered with `members`. - If false or empty list, do not select any inherited member. Default: `False`. - members (list[str] | bool | None): A boolean, or an explicit list of members to render. - If true, select all members without further filtering. - If false or empty list, do not render members. - If none, select all members and apply further filtering with filters and docstrings. Default: `None`. - members_order (str): The members ordering to use. Options: `alphabetical` - order by the members names, - `source` - order members as they appear in the source file. Default: `"alphabetical"`. - filters (list[str] | None): A list of filters applied to filter objects based on their name. - A filter starting with `!` will exclude matching objects instead of including them. - The `members` option takes precedence over `filters` (filters will still be applied recursively - to lower members in the hierarchy). Default: `["!^_[^_]"]`. - group_by_category (bool): Group the object's children by categories: attributes, classes, functions, and modules. Default: `True`. - show_submodules (bool): When rendering a module, show its submodules recursively. Default: `False`. - summary (bool | dict[str, bool]): Whether to render summaries of modules, classes, functions (methods) and attributes. - show_labels (bool): Whether to show labels of the members. Default: `True`. - - Attributes: Docstrings options: - docstring_style (str): The docstring style to use: `google`, `numpy`, `sphinx`, or `None`. Default: `"google"`. - docstring_options (dict): The options for the docstring parser. See [docstring parsers](https://mkdocstrings.github.io/griffe/reference/docstrings/) and their options in Griffe docs. - docstring_section_style (str): The style used to render docstring sections. Options: `table`, `list`, `spacy`. Default: `"table"`. - merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`. - relative_crossrefs (bool): Whether to enable the relative crossref syntax. Default: `False`. - scoped_crossrefs (bool): Whether to enable the scoped crossref ability. Default: `False`. - show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`. - show_docstring_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`. - show_docstring_functions (bool): Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: `True`. - show_docstring_classes (bool): Whether to display the "Classes" section in the object's docstring. Default: `True`. - show_docstring_modules (bool): Whether to display the "Modules" section in the object's docstring. Default: `True`. - show_docstring_description (bool): Whether to display the textual block (including admonitions) in the object's docstring. Default: `True`. - show_docstring_examples (bool): Whether to display the "Examples" section in the object's docstring. Default: `True`. - show_docstring_other_parameters (bool): Whether to display the "Other Parameters" section in the object's docstring. Default: `True`. - show_docstring_parameters (bool): Whether to display the "Parameters" section in the object's docstring. Default: `True`. - show_docstring_raises (bool): Whether to display the "Raises" section in the object's docstring. Default: `True`. - show_docstring_receives (bool): Whether to display the "Receives" section in the object's docstring. Default: `True`. - show_docstring_returns (bool): Whether to display the "Returns" section in the object's docstring. Default: `True`. - show_docstring_warns (bool): Whether to display the "Warns" section in the object's docstring. Default: `True`. - show_docstring_yields (bool): Whether to display the "Yields" section in the object's docstring. Default: `True`. - - Attributes: Signatures/annotations options: - annotations_path (str): The verbosity for annotations path: `brief` (recommended), or `source` (as written in the source). Default: `"brief"`. - line_length (int): Maximum line length when formatting code/signatures. Default: `60`. - show_signature (bool): Show methods and functions signatures. Default: `True`. - show_signature_annotations (bool): Show the type annotations in methods and functions signatures. Default: `False`. - signature_crossrefs (bool): Whether to render cross-references for type annotations in signatures. Default: `False`. - separate_signature (bool): Whether to put the whole signature in a code block below the heading. - If a formatter (Black or Ruff) is installed, the signature is also formatted using it. Default: `False`. - unwrap_annotated (bool): Whether to unwrap `Annotated` types to show only the type without the annotations. Default: `False`. - modernize_annotations (bool): Whether to modernize annotations, for example `Optional[str]` into `str | None`. Default: `False`. - """ - def __init__( - self, - *args: Any, - config_file_path: str | None = None, - paths: list[str] | None = None, - locale: str = "en", - load_external_modules: bool | None = None, - **kwargs: Any, - ) -> None: + def __init__(self, config: PythonConfig, base_dir: Path, **kwargs: Any) -> None: """Initialize the handler. Parameters: - *args: Handler name, theme and custom templates. - config_file_path: The MkDocs configuration file path. - paths: A list of paths to use as Griffe search paths. - locale: The locale to use when rendering content. - load_external_modules: Load external modules when resolving aliases. - **kwargs: Same thing, but with keyword arguments. + config: The handler configuration. + base_dir: The base directory of the project. + **kwargs: Arguments passed to the parent constructor. """ - super().__init__(*args, **kwargs) + super().__init__(**kwargs) + + self.config = config + self.base_dir = base_dir + + # YORE: Bump 2: Replace block with `self.global_options = config.options`. + global_extra, global_options = PythonOptions._extract_extra(config.options) + if global_extra: + _warn_extra_options(global_extra.keys()) # type: ignore[arg-type] + self._global_extra = global_extra + self.global_options = global_options # Warn if user overrides base templates. - if custom_templates := kwargs.get("custom_templates", ()): - config_dir = Path(config_file_path or "./mkdocs.yml").parent - for theme_dir in config_dir.joinpath(custom_templates, "python").iterdir(): + if self.custom_templates: + for theme_dir in base_dir.joinpath(self.custom_templates, "python").iterdir(): if theme_dir.joinpath("_base").is_dir(): logger.warning( f"Overriding base template '{theme_dir.name}/_base/