A Python handler for mkdocstrings.
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
+
+
+
+---
+
+Silver sponsors
+
+
+
+
+
Bronze sponsors
+
+
+
+
- special - private - property - read-only -
- - -### Recommended style (Material) - -Here are some CSS rules for the -[*Material for MkDocs*](https://squidfunk.github.io/mkdocs-material/) theme: - -```css -/* Indentation. */ -div.doc-contents:not(.first) { - padding-left: 25px; - border-left: .05rem solid var(--md-typeset-table-color); -} - -/* Mark external links as such. */ -a.autorefs-external::after { - /* https://primer.style/octicons/arrow-up-right-24 */ - background-image: url('data:image/svg+xml,'); - content: ' '; - - display: inline-block; - position: relative; - top: 0.1em; - margin-left: 0.2em; - margin-right: 0.1em; - - height: 1em; - width: 1em; - border-radius: 100%; - background-color: var(--md-typeset-a-color); -} -a.autorefs-external:hover::after { - background-color: var(--md-accent-fg-color); -} - -``` - -### Recommended style (ReadTheDocs) - -Here are some CSS rules for the built-in *ReadTheDocs* theme: - -```css -/* Indentation. */ -div.doc-contents:not(.first) { - padding-left: 25px; - border-left: .05rem solid rgba(200, 200, 200, 0.2); -} -``` - -## Templates - -Templates are organized into the following tree: - -```tree result="text" -theme/ - attribute.html - children.html - class.html - docstring/ - admonition.html - attributes.html - examples.html - other_parameters.html - parameters.html - raises.html - receives.html - returns.html - warns.html - yields.html - docstring.html - expression.html - function.html - labels.html - module.html - signature.html -``` - -See them [in the repository](https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/). -See the general *mkdocstrings* documentation to learn how to override them: https://mkdocstrings.github.io/theming/#templates. - -In preparation for Jinja2 blocks, which will improve customization, -each one of these templates extends in fact a base version in `theme/_base`. Example: - -```html+jinja title="theme/docstring/admonition.html" -{% extends "_base/docstring/admonition.html" %} -``` - -```html+jinja title="theme/_base/docstring/admonition.html" -{{ log.debug() }} -
-
-```
-
-It means you will be able to customize only *parts* of a template
-without having to fully copy-paste it in your project:
-
-```jinja title="templates/theme/docstring.html"
-{% extends "_base/docstring.html" %}
-{% block contents %}
- {{ block.super }}
- Additional contents
-{% endblock contents %}
-```
-
-WARNING: **Block-level customization is not ready yet. We welcome [suggestions](https://github.com/mkdocstrings/python/issues/new).**
diff --git a/docs/gen_ref_nav.py b/docs/gen_ref_nav.py
deleted file mode 100755
index 14f0f4ad..00000000
--- a/docs/gen_ref_nav.py
+++ /dev/null
@@ -1,32 +0,0 @@
-"""Generate the code reference pages and navigation."""
-
-from pathlib import Path
-
-import mkdocs_gen_files
-
-nav = mkdocs_gen_files.Nav()
-
-for path in sorted(Path("src").rglob("*.py")):
- module_path = path.relative_to("src").with_suffix("")
- doc_path = path.relative_to("src").with_suffix(".md")
- full_doc_path = Path("reference", doc_path)
-
- parts = tuple(module_path.parts)
-
- if parts[-1] == "__init__":
- parts = parts[:-1]
- doc_path = doc_path.with_name("index.md")
- full_doc_path = full_doc_path.with_name("index.md")
- elif parts[-1] == "__main__":
- continue
-
- nav[parts] = doc_path.as_posix()
-
- with mkdocs_gen_files.open(full_doc_path, "w") as fd:
- ident = ".".join(parts)
- fd.write(f"::: {ident}")
-
- mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path)
-
-with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
- nav_file.writelines(nav.build_literate_nav())
diff --git a/docs/index.md b/docs/index.md
index 612c7a5e..82377e21 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1 +1,7 @@
+---
+title: Overview
+hide:
+- feedback
+---
+
--8<-- "README.md"
diff --git a/docs/js/feedback.js b/docs/js/feedback.js
new file mode 100644
index 00000000..f97321a5
--- /dev/null
+++ b/docs/js/feedback.js
@@ -0,0 +1,14 @@
+const feedback = document.forms.feedback;
+feedback.hidden = false;
+
+feedback.addEventListener("submit", function(ev) {
+ ev.preventDefault();
+ const commentElement = document.getElementById("feedback");
+ commentElement.style.display = "block";
+ feedback.firstElementChild.disabled = true;
+ const data = ev.submitter.getAttribute("data-md-value");
+ const note = feedback.querySelector(".md-feedback__note [data-md-value='" + data + "']");
+ if (note) {
+ note.hidden = false;
+ }
+})
diff --git a/docs/license.md b/docs/license.md
index cdacdfef..5b25a00f 100644
--- a/docs/license.md
+++ b/docs/license.md
@@ -1,3 +1,11 @@
+---
+title: License
+hide:
+- feedback
+---
+
+# License
+
```
--8<-- "LICENSE"
```
diff --git a/docs/reference/api.md b/docs/reference/api.md
new file mode 100644
index 00000000..587e99db
--- /dev/null
+++ b/docs/reference/api.md
@@ -0,0 +1,9 @@
+---
+title: API reference
+hide:
+- navigation
+---
+
+# ::: mkdocstrings_handlers.python
+ options:
+ show_submodules: true
diff --git a/docs/snippets/package/__init__.py b/docs/snippets/package/__init__.py
new file mode 100644
index 00000000..b19123b7
--- /dev/null
+++ b/docs/snippets/package/__init__.py
@@ -0,0 +1,19 @@
+from importlib import metadata
+
+def get_version(dist: str = "mkdocstrings-python") -> str:
+ """Get version of the given distribution.
+
+ Parameters:
+ dist: A distribution name.
+
+ Returns:
+ A version number.
+ """
+ try:
+ return metadata.version(dist)
+ except metadata.PackageNotFoundError:
+ return "0.0.0"
+
+
+current_version: str = get_version(dist="mkdocstrings-python")
+"""Current package version."""
diff --git a/docs/snippets/package/generics.py b/docs/snippets/package/generics.py
new file mode 100644
index 00000000..0aef12d4
--- /dev/null
+++ b/docs/snippets/package/generics.py
@@ -0,0 +1,49 @@
+"""Some module showing generics.
+
+Type Aliases:
+ SomeType: Some type alias.
+"""
+
+type SomeType[Z] = int | list[Z]
+"""Some type alias.
+
+Type parameters:
+ Z: Some type parameter.
+"""
+
+
+class MagicBag[T: (str, bytes) = str](list[T]):
+ """A magic bag of items.
+
+ Type parameters:
+ T: Some type.
+ """
+
+ def __init__[U: (int, bool)](self, *args: T, flag1: U | None = None, flag2: U | None = None) -> None:
+ """Initialize bag.
+
+ Type parameters:
+ U: Some flag type.
+
+ Parameters:
+ flag1: Some flag.
+ flag2: Some flag.
+ """
+ super().__init__(args)
+ self.flag1 = flag1
+ self.flag2 = flag2
+
+ def mutate[K](self, item: T, into: K) -> K:
+ """Shake the bag to mutate an item into something else (and eject it).
+
+ Type parameters:
+ K: Some other type.
+
+ Parameters:
+ item: The item to mutate.
+ into: Mutate the item into something like this.
+
+ Returns:
+ The mutated item.
+ """
+ ...
diff --git a/docs/snippets/package/modern.py b/docs/snippets/package/modern.py
new file mode 100644
index 00000000..c992b5df
--- /dev/null
+++ b/docs/snippets/package/modern.py
@@ -0,0 +1,3 @@
+from typing import Optional, Union, List
+
+example: Optional[Union[int, List[int]]] = None
diff --git a/docs/usage.md b/docs/usage.md
deleted file mode 100644
index de28ca16..00000000
--- a/docs/usage.md
+++ /dev/null
@@ -1,294 +0,0 @@
-# Usage
-
-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).
-
-The tool used by the Python handler to collect documentation from Python source code
-is [Griffe](https://mkdocstrings.github.io/griffe). The word "griffe" can sometimes be used instead of "signature" in french.
-Griffe is able to visit the Abstract Syntax Tree (AST) of the source code to extract useful information.
-It is also able to execute the code (by importing it) and introspect objects in memory
-when source code is not available. Finally, it can parse docstrings following different styles,
-see [Supported docstrings styles](#supported-docstrings-styles).
-
-Like every handler, the Python handler accepts both **global** and **local** options.
-
-## Global-only options
-
-Some options are **global only**, and go directly under the handler's name.
-
-- `import`: this option is used to import Sphinx-compatible objects inventories from other
- documentation sites. For example, you can import the standard library
- objects inventory like this:
-
- ```yaml title="mkdocs.yml"
- plugins:
- - mkdocstrings:
- handlers:
- python:
- import:
- - https://docs.python-requests.org/en/master/objects.inv
- ```
-
- 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.
-
- NOTE: This global option is common to *all* handlers, however
- they might implement it differently (or not even implement it).
-
-- `paths`: this option is used to provide filesystem paths in which to search for Python modules.
- Non-absolute paths are computed as relative to MkDocs configuration file. Example:
-
- ```yaml title="mkdocs.yml"
- plugins:
- - mkdocstrings:
- handlers:
- python:
- paths: [src] # search packages in the src folder
- ```
-
- More details at [Finding modules](#finding-modules).
-
-## Global/local options
-
-The other options can be used both globally *and* locally, under the `options` key.
-For example, globally:
-
-```yaml title="mkdocs.yml"
-plugins:
-- mkdocstrings:
- handlers:
- python:
- options:
- do_something: true
-```
-
-...and locally, overriding the global configuration:
-
-```md title="docs/some_page.md"
-::: package.module.class
- options:
- do_something: false
-```
-
-These options affect how the documentation is collected from sources and renderered:
-headings, members, docstrings, etc.
-
-::: mkdocstrings_handlers.python.handler.PythonHandler.default_config
- options:
- show_root_toc_entry: false
-
-## Supported docstrings styles
-
-Griffe supports the Google-style, Numpy-style and Sphinx-style docstring formats.
-The style used by default is the Google-style.
-You can configure what style you want to use with
-the `docstring_style` and `docstring_options` options,
-both globally or locally, i.e. per autodoc instruction.
-
-- Google: see [Napoleon's documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
-- Numpy: see [Numpydoc's documentation](https://numpydoc.readthedocs.io/en/latest/format.html).
-- Sphinx: see [Sphinx's documentation](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html).
-
-See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/).
-
-NOTE: As Numpy-style is partially supported by the underlying parser,
-you may experience problems in the building process if your docstring
-has a `Methods` section in the class docstring
-(see [#366](https://github.com/mkdocstrings/mkdocstrings/issues/366)).
-
-### Google-style admonitions
-
-With Google-style docstrings, any section that is not recognized will be transformed into its admonition equivalent.
-For example:
-
-=== "Docstring"
- ```python
- """
- Note:
- It looks like a section, but it will be rendered as an admonition.
-
- Tip: You can even choose a title.
- 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.**
- This admonition has a custom title!
-
-## Finding modules
-
-There are multiple ways to tell the handler where to find your packages/modules.
-
-**The recommended method is to use the `paths` option, as it's the only one
-that works with the `-f` option of MkDocs, allowing to build the documentation
-from any location on the file system.** Indeed, the paths provided with the
-`paths` option are computed as relative to the configuration file (mkdocs.yml),
-so that the current working directory has no impact on the build process:
-*you can build the docs from any location on your filesystem*.
-
-### Using the `paths` option
-
-TIP: **This is the recommended method.**
-
-1. mkdocs.yml in root, package in root
- ```tree
- root/
- mkdocs.yml
- package/
- ```
-
- ```yaml title="mkdocs.yml"
- plugins:
- - mkdocstrings:
- handlers:
- python:
- paths: [.] # actually not needed, default
- ```
-
-1. mkdocs.yml in root, package in subfolder
- ```tree
- root/
- mkdocs.yml
- src/
- package/
- ```
-
- ```yaml title="mkdocs.yml"
- plugins:
- - mkdocstrings:
- handlers:
- python:
- paths: [src]
- ```
-
-1. mkdocs.yml in subfolder, package in root
- ```tree
- root/
- docs/
- mkdocs.yml
- package/
- ```
-
- ```yaml title="mkdocs.yml"
- plugins:
- - mkdocstrings:
- handlers:
- python:
- paths: [..]
- ```
-
-1. mkdocs.yml in subfolder, package in subfolder
- ```tree
- root/
- docs/
- mkdocs.yml
- src/
- package/
- ```
-
- ```yaml title="mkdocs.yml"
- plugins:
- - mkdocstrings:
- handlers:
- python:
- paths: [../src]
- ```
-
-Except for case 1, which is supported by default, **we strongly recommend
-to set the path to your packages using this option, even if it works without it**
-(for example because your project manager automatically adds `src` to PYTHONPATH),
-to make sure anyone can build your docs from any location on their filesystem.
-
-### Using the PYTHONPATH environment variable
-
-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 to use the [`paths` method](#using-the-paths-option) instead.
-
-You can take advantage of the usual Python loading mechanisms.
-In Bash and other shells, you can run your command like this
-(note the prepended `PYTHONPATH=...`):
-
-1. mkdocs.yml in root, package in root
- ```tree
- root/
- mkdocs.yml
- package/
- ```
-
- ```bash
- PYTHONPATH=. mkdocs build # actually not needed, default
- ```
-
-1. mkdocs.yml in root, package in subfolder
- ```tree
- root/
- mkdocs.yml
- src/
- package/
- ```
-
- ```bash
- PYTHONPATH=src mkdocs build
- ```
-
-1. mkdocs.yml in subfolder, package in root
- ```tree
- root/
- docs/
- mkdocs.yml
- package/
- ```
-
- ```bash
- PYTHONPATH=. mkdocs build -f docs/mkdocs.yml
- ```
-
-1. mkdocs.yml in subfolder, package in subfolder
- ```tree
- root/
- docs/
- mkdocs.yml
- src/
- package/
- ```
-
- ```bash
- PYTHONPATH=src mkdocs build -f docs/mkdocs.yml
- ```
-
-### Installing your package in the current Python environment
-
-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 to use the [`paths` method](#using-the-paths-option) instead.
-
-Install your package in the current environment, and run MkDocs:
-
-=== "pip"
- ```bash
- . venv/bin/activate
- pip install -e .
- mkdocs build
- ```
-
-=== "PDM"
- ```bash
- pdm install
- pdm run mkdocs build
- ```
-
-=== "Poetry"
- ```bash
- poetry install
- poetry run mkdocs build
- ```
diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md
new file mode 100644
index 00000000..95f9032f
--- /dev/null
+++ b/docs/usage/configuration/docstrings.md
@@ -0,0 +1,1461 @@
+# Docstrings options
+
+[](){#option-docstring_style}
+## `docstring_style`
+
+- **:octicons-package-24: Type [`str`][] :material-equal: `"google"`{ title="default value" }**
+
+
+The docstring style to expect when parsing docstrings.
+
+Possible values:
+
+- `"google"`: see [Google style](../docstrings/google.md).
+- `"numpy"`: see [Numpy style](../docstrings/numpy.md).
+- `"sphinx"`: see [Sphinx style](../docstrings/sphinx.md).
+- `None` (`null` or `~` in YAML): no style at all, parse as regular text.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ docstring_style: google
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+ options:
+ docstring_style: numpy
+```
+
+WARNING: **The style is applied to the specified object only, not its members.** Local `docstring_style` options (in `:::` instructions) will only be applied to the specified object, and not its members. Instead of changing the style when rendering, we strongly recommend to *set the right style as early as possible*, for example by using the [auto-style](https://mkdocstrings.github.io/griffe/reference/docstrings/#auto-style) (sponsors only), or with a custom Griffe extension
+
+
+/// admonition | Preview
+ type: preview
+
+Every style gets rendered the same way.
+Here are some docstring examples.
+
+//// tab | Google
+```python
+def greet(name: str) -> str:
+ """Greet someone.
+
+ Parameters:
+ name: The name of the person to greet.
+
+ Returns:
+ A greeting message.
+ """
+ return f"Hello {name}!"
+```
+////
+
+//// tab | Numpy
+```python
+def greet(name: str) -> str:
+ """Greet someone.
+
+ Parameters
+ ----------
+ name
+ The name of the person to greet.
+
+ Returns
+ -------
+ A greeting message.
+ """
+ return f"Hello {name}!"
+```
+////
+
+//// tab | Sphinx
+```python
+def greet(name: str) -> str:
+ """Greet someone.
+
+ :param name: The name of the person to greet.
+ :return: A greeting message.
+ """
+ return f"Hello {name}!"
+```
+////
+///
+
+[](){#option-docstring_options}
+## `docstring_options`
+
+- **:octicons-package-24: Type [`dict`][] :material-equal: `{}`{ title="default value" }**
+
+
+The options for the docstring parser.
+
+- [Google-style options](https://mkdocstrings.github.io/griffe/docstrings/#parser-options){ .external }
+- [Numpydoc-style options](https://mkdocstrings.github.io/griffe/docstrings/#parser-options_1){ .external }
+
+The Sphinx style does not offer any option.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ docstring_options:
+ ignore_init_summary: false
+ trim_doctest_flags: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+ options:
+ docstring_options:
+ ignore_init_summary: true
+ trim_doctest_flags: false
+```
+
+```python
+class PrintOK:
+ """Class docstring."""
+
+ def __init__(self):
+ """Initialize the instance.
+
+ Examples:
+ >>> PrintOK() # doctest: +NORMALIZE_WHITESPACE
+ ok
+ """
+ print("ok")
+```
+
+/// admonition | Preview
+ type: preview
+
+//// tab | Ignore init summary, trim doctest flags
+{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}
- {{ section.value.contents|convert_markdown(heading_level, html_id) }} -PrintOK
+Class docstring.
+__init__
+Examples:
+ +```pycon +>>> PrintOK() +ok +``` +//// + +//// tab | Keep init summary and doctest flags +PrintOK
+Class docstring.
+__init__
+Initialize the instance.
+Examples:
+ +```pycon +>>> PrintOK() # doctest: +NORMALIZE_WHITESPACE +ok +``` +//// +/// + +[](){#option-docstring_section_style} +## `docstring_section_style` + +- **:octicons-package-24: Type [`str`][] :material-equal: `"table"`{ title="default value" }** + + +The style used to render docstring sections. + +A section is a block of text that has a special meaning in a docstring. +There are sections for documenting attributes of an object, +parameters of a function, exceptions raised by a function, +the return value of a function, etc. + +Sections are parsed as structured data and can therefore be rendered +in different ways. Possible values: + +- `"table"`: a simple table, usually with type, name and description columns +- `"list"`: a simple list, akin to what you get with the [ReadTheDocs Sphinx theme]{ .external } +- `"spacy"`: a poor implementation of the amazing tables in [Spacy's documentation]{ .external } + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + docstring_section_style: table +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + docstring_section_style: list +``` + +/// admonition | Preview + type: preview + +//// tab | Table +Tables work well when you have lots of items with short names, type annotations, descriptions, etc.. +With longer strings, the columns risk getting squished horizontally. +In that case, the Spacy tables can help. + +**Parameters:** + +**Type** | **Name** | **Description** | **Default** +---------- | ----------- | ------------------------ | ----------- +[`int`][] | `threshold` | Threshold for something. | *required* +[`bool`][] | `flag` | Enable something. | `False` + +**Other Parameters:** + +**Type** | **Name** | **Description** | **Default** +---------- | ----------- | ------------------------ | ----------- +list [int \| float ]VacuumType \| Literal ["regular"]list [int \| float ]VacuumType \| Literal ["regular"]**TYPE:** [`int`][] DEFAULT: required +`flag` | Enable something.
**TYPE:** [`bool`][] DEFAULT:
False
+
+**Other Parameters:**
+
+**Name** | **Description**
+----------- | ---------------
+`gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.**TYPE:**
list [int \| float ]**TYPE:**
VacuumType \| Literal ["regular"]VacuumType.PLASMA
+////
+///
+
+[](){#option-merge_init_into_class}
+## `merge_init_into_class`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+
+
+Whether to merge the `__init__` method into the class' signature and docstring.
+
+By default, only the class name is rendered in headings.
+When merging, the `__init__` method parameters are added after the class name,
+like a signature, and the `__init__` method docstring is appended to the class' docstring.
+This option is well used in combination with the `ignore_init_summary` [docstring option][docstring_options],
+to discard the first line of the `__init__` docstring which is not often useful.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ docstring_options:
+ ignore_init_summary: false
+ merge_init_into_class: false
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+ options:
+ docstring_options:
+ ignore_init_summary: true
+ merge_init_into_class: true
+```
+
+```python
+class Thing:
+ """A class for things."""
+
+ def __init__(self, value: int = 0):
+ """Initialize a thing.
+
+ Parameters:
+ value: The thing's value.
+ """
+ self.value = value
+```
+
+/// admonition | Preview
+ type: preview
+
+//// tab | Merged, summary discarded
+Thing(value=0)
+Class docstring.
+Parameters:
+ +**Type** | **Name** | **Description** | **Default** +--------- | -------- | ------------------ | ----------- +[`int`][] | `value` | The thing's value. | `0` +//// + +//// tab | Unmerged, summary kept +Thing
+Class docstring.
+__init__(value=0)
+Initialize a thing.
+Parameters:
+ +**Type** | **Name** | **Description** | **Default** +--------- | -------- | ------------------ | ----------- +[`int`][] | `value` | The thing's value. | `0` +//// +/// + +[](){#option-relative_crossrefs} +## `relative_crossrefs` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to enable the relative-crossref syntax. + +The relative-crossref syntax lets you reference the current object or its parent by prefixing a crossref identifier with dots. For example, to cross-reference the current object's `name` member, you can write `[link to name attribute][.name]`. The "current object" is the object containing the docstring being rendered. + + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + relative_crossrefs: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + relative_crossrefs: true +``` + +/// admonition | Examples + type: preview + +```python title="pkg/module.py" +"""Summary. + +- Link to [`module`][.]. +- Link to [`module_attribute`][.module_attribute]. +- Link to [`Class`][.Class]. +- Link to [`class_attribute`][.Class.class_attribute]. +- Link to [`instance_attribute`][.Class.instance_attribute]. +- Link to [`method`][.Class.method]. +""" + +module_attribute = 0 +"""Summary. + +- Link to [`module`][..]. +- Link to [`module_attribute`][.]. +- Link to [`Class`][..Class]. +- Link to [`class_attribute`][..Class.class_attribute]. +- Link to [`instance_attribute`][..Class.instance_attribute]. +- Link to [`method`][..Class.method]. +""" + +class Class: + """Summary. + + - Link to [`module`][..]. + - Link to [`module_attribute`][..module_attribute]. + - Link to [`Class`][.]. + - Link to [`class_attribute`][.class_attribute]. + - Link to [`instance_attribute`][.instance_attribute]. + - Link to [`method`][.method]. + """ + + class_attribute = 0 + """Summary. + + - Link to [`module`][...]. + - Link to [`module_attribute`][...module_attribute]. + - Link to [`Class`][..]. + - Link to [`class_attribute`][.]. + - Link to [`instance_attribute`][..instance_attribute]. + - Link to [`method`][..method]. + """ + + def __init__(self): + """Summary. + + - Link to [`module`][...]. + - Link to [`module_attribute`][...module_attribute]. + - Link to [`Class`][..]. + - Link to [`class_attribute`][..class_attribute]. + - Link to [`instance_attribute`][..instance_attribute]. + - Link to [`method`][..method]. + """ + self.instance_attribute = 0 + """Summary. + + - Link to [`module`][...]. + - Link to [`module_attribute`][...module_attribute]. + - Link to [`Class`][..]. + - Link to [`class_attribute`][..class_attribute]. + - Link to [`instance_attribute`][.]. + - Link to [`method`][..method]. + """ + + def method(self): + """Summary. + + - Link to [`module`][...]. + - Link to [`module_attribute`][...module_attribute]. + - Link to [`Class`][..]. + - Link to [`class_attribute`][..class_attribute]. + - Link to [`instance_attribute`][..instance_attribute]. + - Link to [`method`][.]. + """ +``` + +/// + +INFO: **There is an alternative, third-party Python handler that handles relative references: [mkdocstrings-python-xref](https://github.com/analog-garage/mkdocstrings-python-xref).** + +[](){#option-scoped_crossrefs} +## `scoped_crossrefs` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to enable scoped cross-references. + +With scoped cross-references, you can write identifiers as if you wanted to access them from the current object's scope. The scoping rules do not exactly match Python's: you can reference members and siblings too, without prefixing with `self.` or `cls.`. + +The following order is applied when resolving a name in a given scope: + +1. member of the current object +2. parent class +3. repeat 1-2 within parent's scope + +In practice, it means that the name is first looked up in members, then it is compared against the parent name (only if it's a class), then it is looked up in siblings. It continues climbing up the object tree until there's no parent, in which case it raises a name resolution error. + +Cross-referencing an imported object will directly link to this object if the objects inventory of the project it comes from was [loaded][inventories]. You won't be able to cross-reference it within your own documentation with scoped references, if you happen to be rendering this external object too. In that case, you can use an absolute reference or a [relative][relative_crossrefs] one instead. + +Another limitation is that you won't be able to reference an external package if its name can be resolved in the current object's scope. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + scoped_crossrefs: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + scoped_crossrefs: true +``` + +/// admonition | Examples + type: preview + +```python title="pkg/module.py" +"""Summary. + +- Link to [`module_attribute`][module_attribute]. +- Link to [`Class`][Class]. +- Link to [`class_attribute`][Class.class_attribute]. +- Link to [`instance_attribute`][Class.instance_attribute]. +- Link to [`method`][Class.method]. +""" + +module_attribute = 0 +"""Summary. + +- Link to [`Class`][Class]. +- Link to [`class_attribute`][Class.class_attribute]. +- Link to [`instance_attribute`][Class.instance_attribute]. +- Link to [`method`][Class.method]. +""" + +class Class: + """Summary. + + - Link to [`module_attribute`][module_attribute]. + - Link to [`class_attribute`][class_attribute]. + - Link to [`instance_attribute`][instance_attribute]. + - Link to [`method`][method]. + """ + + class_attribute = 0 + """Summary. + + - Link to [`module_attribute`][module_attribute]. + - Link to [`Class`][Class]. + - Link to [`instance_attribute`][instance_attribute]. + - Link to [`method`][method]. + """ + + def __init__(self): + """Summary. + + - Link to [`module_attribute`][module_attribute]. + - Link to [`Class`][Class]. + - Link to [`class_attribute`][class_attribute]. + - Link to [`instance_attribute`][instance_attribute]. + - Link to [`method`][method]. + """ + self.instance_attribute = 0 + """Summary. + + - Link to [`module_attribute`][module_attribute]. + - Link to [`Class`][Class]. + - Link to [`class_attribute`][class_attribute]. + - Link to [`method`][method]. + """ + + def method(self): + """Summary. + + - Link to [`module_attribute`][module_attribute]. + - Link to [`Class`][Class]. + - Link to [`class_attribute`][class_attribute]. + - Link to [`instance_attribute`][instance_attribute]. + """ +``` + +/// + +[](){#option-show_if_no_docstring} +## `show_if_no_docstring` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Show the object heading even if it has no docstring or children with docstrings. + +Without an explicit list of [`members`][], members are selected based on [`filters`][], +and then filtered again to keep only those with docstrings. Checking if a member has a docstring +is done recursively: if at least one of its direct or indirect members (lower in the tree) +has a docstring, the member is rendered. If the member does not have a docstring, +and none of its members have a docstring, it is excluded. + +With this option you can tell the Python handler to skip the docstring check. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_if_no_docstring: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_if_no_docstring: true +``` + +```python +def function_without_docstring(): + ... + + +def function_with_docstring(): + """Hello.""" + + +class ClassWithoutDocstring: + def method_without_docstring(self): + ... + + def method_with_docstring(self): + """Hello.""" +``` + +/// admonition | Preview + type: preview + +//// tab | Show +function_without_docstring
+function_with_docstring
+Hello.
+ClassWithoutDocstring
+method_without_docstring
+method_with_docstring
+Hello.
+//// + +//// tab | Don't show +function_with_docstring
+Hello.
+ClassWithoutDocstring
+method_with_docstring
+Hello.
+//// +/// + +[](){#option-show_docstring_attributes} +## `show_docstring_attributes` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Attributes" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_attributes: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_attributes: false +``` + +```python +class Class: + """Summary. + + Attributes: + attr: Some attribute. + """ + + attr: int = 1 +``` + +/// admonition | Preview + type: preview + +//// tab | With attributes +Class
+Summary.
+Attributes:
+ +**Type** | **Name** | **Description** +--------- | -------- | --------------- +[`int`][] | `attr` | Some attribute. +//// + +//// tab | Without attributes +Class
+Summary.
+//// +/// + +[](){#option-show_docstring_functions} +## `show_docstring_functions` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Functions" or "Methods" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_functions: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_functions: false +``` + +```python +"""Summary. + +Functions: + foo: Some function. +""" + + +def foo(): + ... + + +class Class: + """Summary. + + Methods: + bar: Some method. + """ + + def bar(self): + ... +``` + +/// admonition | Preview + type: preview + +//// tab | With functions +module
+Summary.
+Functions:
+ +**Name** | **Description** +-------- | --------------- +`foo` | Some function. + +Class
+Summary.
+Methods:
+ +**Name** | **Description** +-------- | --------------- +`bar` | Some method. +//// + +//// tab | Without functions +module
+Summary.
+Class
+Summary.
+//// +/// + +[](){#option-show_docstring_classes} +## `show_docstring_classes` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Classes" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_classes: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_classes: false +``` + +```python +"""Summary. + +Classes: + Class: Some class. +""" + + +class Class: + """Summary.""" +``` + +/// admonition | Preview + type: preview + +//// tab | With classes +module
+Summary.
+Classes:
+ +**Name** | **Description** +-------- | --------------- +`Class` | Some class. + +Class
+Summary.
+//// + +//// tab | Without classes +module
+Summary.
+Class
+Summary.
+//// +/// + +[](){#option-show_docstring_type_aliases} +## `show_docstring_type_aliases` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + +Whether to render the "Type Aliases" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_type_aliases: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_type_aliases: false +``` + +```python +"""Summary. + +Type Aliases: + TypeAlias: Some type alias. +""" + + +type TypeAlias = int +"""Summary.""" +``` + +/// admonition | Preview + type: preview + +//// tab | With type_aliases +module
+Summary.
+Type Aliases:
+ +**Name** | **Description** +------------ | ---------------- +`TypeAlias` | Some type alias. + +TypeAlias
+Summary.
+//// + +//// tab | Without classes +module
+Summary.
+TypeAlias
+Summary.
+//// +/// + +[](){#option-show_docstring_modules} +## `show_docstring_modules` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Modules" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_modules: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_modules: false +``` + +```tree +module/ + __init__.py + submodule.py +``` + +```python title="module/__init__.py" +"""Summary. + +Modules: + submodule: Some module. +""" +``` + +/// admonition | Preview + type: preview + +//// tab | With modules +module
+Summary.
+Modules:
+ +**Name** | **Description** +----------- | --------------- +`submodule` | Some module. + +//// + +//// tab | Without modules +module
+Summary.
+//// +/// + +[](){#option-show_docstring_description} +## `show_docstring_description` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the textual blocks (including admonitions) of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_description: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_description: false +``` + +```python +class Class: + """Summary. + + Long description. + + Warning: Deprecated + Stop using this class. + + Attributes: + attr: Some attribute. + """ + + attr: int = 1 +``` + +/// admonition | Preview + type: preview + +//// tab | With description blocks +Class
+Summary.
+Long description.
+Deprecated
Stop using this class.
Attributes:
+ +**Type** | **Name** | **Description** +--------- | -------- | --------------- +[`int`][] | `attr` | Some attribute. +//// + +//// tab | Without description blocks +Class
+Attributes:
+ +**Type** | **Name** | **Description** +--------- | -------- | --------------- +[`int`][] | `attr` | Some attribute. +//// +/// + +[](){#option-show_docstring_examples} +## `show_docstring_examples` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Examples" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_examples: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_examples: false +``` + +```python +def print_hello(): + """Print hello. + + Examples: + >>> print("hello") + hello + """ + print("hello") +``` + +/// admonition | Preview + type: preview + +//// tab | With examples +print_hello
+Print hello.
+Examples:
+ +```pycon +>>> print("hello") +hello +``` +//// + +//// tab | Without examples +print_hello
+Print hello.
+//// +/// + +[](){#option-show_docstring_other_parameters} +## `show_docstring_other_parameters` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Other Parameters" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_other_parameters: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_other_parameters: false +``` + +```python +def do_something(**kwargs): + """Do something. + + Other parameters: + whatever (int): Some integer. + """ +``` + +/// admonition | Preview + type: preview + +//// tab | With other parameters +do_something
+Do something.
+Other parameters:
+ +**Type** | **Name** | **Description** +--------- | ---------- | --------------- +[`int`][] | `whatever` | Some integer. +//// + +//// tab | Without other parameters +do_something
+Do something.
+//// +/// + +[](){#option-show_docstring_parameters} +## `show_docstring_parameters` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Parameters" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_parameters: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_parameters: false +``` + +```python +def do_something(whatever: int = 0): + """Do something. + + Parameters: + whatever: Some integer. + """ +``` + +/// admonition | Preview + type: preview + +//// tab | With parameters +do_something
+Do something.
+Parameters:
+ +**Type** | **Name** | **Description** | **Default** +--------- | ---------- | --------------- | ----------- +[`int`][] | `whatever` | Some integer. | `0` +//// + +//// tab | Without parameters +do_something
+Do something.
+//// +/// + +[](){#option-show_docstring_raises} +## `show_docstring_raises` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Raises" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_raises: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_raises: false +``` + +```python +def raise_runtime_error(): + """Raise a runtime error. + + Raises: + RuntimeError: Not good. + """ + raise RuntimeError +``` + +/// admonition | Preview + type: preview + +//// tab | With exceptions +raise_runtime_error
+Raise a runtime error.
+Raises:
+ +**Type** | **Description** +------------------ | --------------- +[`RuntimeError`][] | Not good. +//// + +//// tab | Without exceptions +raise_runtime_error
+Raise a runtime error.
+//// +/// + +[](){#option-show_docstring_receives} +## `show_docstring_receives` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Receives" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_receives: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_receives: false +``` + +```python +def iter_skip( + iterable: Iterable[T], + initial_skip: int = 0, +) -> Generator[T, int, None]: + """Iterate and skip elements. + + Receives: + skip: Number of elements to skip. + """ + skip = initial_skip + for element in iterable: + if skip or 0 > 0: + skip -= 1 + else: + skip = yield element +``` + +/// admonition | Preview + type: preview + +//// tab | With received values +iter_skip
+Iterate and skip elements.
+Receives:
+ +**Type** | **Description** +--------- | --------------- +[`int`][] | Number of elements to skip. +//// + +//// tab | Without received values +iter_skip
+Iterate and skip elements.
+//// +/// + +[](){#option-show_docstring_returns} +## `show_docstring_returns` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Returns" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_returns: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_returns: false +``` + +```python +def rand() -> int: + """Return a random number. + + Returns: + A random number. + """ + return random.randint(0, 1000) +``` + +/// admonition | Preview + type: preview + +//// tab | With return value +rand
+Return a random number.
+Returns:
+ +**Type** | **Description** +--------- | --------------- +[`int`][] | A random number. +//// + +//// tab | Without return value +rand
+Return a random number.
+//// +/// + +[](){#option-show_docstring_type_parameters} +## `show_docstring_type_parameters` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Type Parameters" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_type_parameters: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_type_parameters: false +``` + +```python +class AClass[X: (int, str) = str]: + """Represents something. + + Type Parameters: + X: Something. + """ +``` + +/// admonition | Preview + type: preview + +//// tab | With parameters +AClass
+Represents something.
+Type Parameters:
+ +**Name** | **Bound or Constraints** | **Description** | **Default** +---------- | ------------------------ | --------------- | ----------- +`whatever` | `(int, str)` | Something. | `str` +//// + +//// tab | Without parameters +AClass
+Represents something.
+//// +/// + +[](){#option-show_docstring_warns} +## `show_docstring_warns` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Warns" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_warns: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_warns: false +``` + +```python +def warn(): + """Warn user. + + Warns: + UserWarning: When this is inappropriate. + """ + warnings.warn(UserWarning("This is inappropriate")) +``` + +/// admonition | Preview + type: preview + +//// tab | With warnings +warn
+Warn user.
+Warns:
+ +**Type** | **Description** +----------------- | --------------- +[`UserWarning`][] | When this is inappropriate. +//// + +//// tab | Without warnings +warn
+Warn user.
+//// +/// + +[](){#option-show_docstring_yields} +## `show_docstring_yields` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Yields" section of docstrings. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_docstring_yields: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_docstring_yields: false +``` + +```python +def iter_skip( + iterable: Iterable[T], + initial_skip: int = 0, +) -> Generator[T, int, None]: + """Iterate and skip elements. + + Yields: + Elements of the iterable. + """ + skip = initial_skip + for element in iterable: + if skip or 0 > 0: + skip -= 1 + else: + skip = yield element +``` + +/// admonition | Preview + type: preview + +//// tab | With yielded values +iter_skip
+Iterate and skip elements.
+Yields:
+ +**Type** | **Description** +--------- | --------------- +`T` | Elements of the iterable. +//// + +//// tab | Without yielded values +iter_skip
+Iterate and skip elements.
+//// +/// diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md new file mode 100644 index 00000000..921f3b27 --- /dev/null +++ b/docs/usage/configuration/general.md @@ -0,0 +1,687 @@ +# General options + +[](){#option-allow_inspection} +## `allow_inspection` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to allow inspecting modules (importing them) +when it is not possible to visit them (parse their source code). + +When loading data for a given package, [Griffe] discovers every Python module, +compiled or not, and inspects or visits them accordingly. + +If you have compiled modules but also provide stubs for them, +you might want to disable the inspection of these modules, +because inspection picks up many more members, +and sometimes the collected data is inaccurate +(depending on the tool that was used to compile the module) +or too low-level/technical for API documentation. + +See also [`force_inspection`](#force_inspection). + +WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `allow_inspection` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + allow_inspection: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + allow_inspection: false +``` + +/// admonition | Preview + type: preview + +//// tab | With inspection +SomeClass
+Docstring of the class.
+__eq__
+Method docstring.
+__weakref__
+Method docstring.
+documented_method
+Method docstring.
+//// + +//// tab | Without inspection +SomeClass
+Docstring of the class.
+documented_method
+Method docstring.
+//// +/// + +[](){#option-backlinks} +## `backlinks` + +- **:octicons-package-24: TypeLiteral ["flat", "tree", False]list [str | dict [str , dict [str , Any ]]]your_func
+Function docstring
+//// + +//// tab | Without find_stubs_package +your_func
+////
+///
+
+[](){#option-force_inspection}
+## `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/).
+
+See also [`allow_inspection`](#allow_inspection).
+
+```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
+```
+
+WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `force_inspection` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards.
+
+[](){#option-inheritance_diagram_direction}
+## `inheritance_diagram_direction`
+
+The direction of the Mermaid chart presenting the inheritance diagram of a class, `TD` by default.
+
+```yaml title="mkdocs.yml"
+extra_javascript:
+- https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js
+```
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ inheritance_diagram_direction: TD
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.object
+ options:
+ inheritance_diagram_direction: TD
+```
+
+/// admonition | Preview
+ type: preview
+
+
+With the following classes:
+
+```python
+class SuperAbstract:
+ """Super abstract class."""
+class Mixin1:
+ """Mixin 1."""
+class Abstract(SuperAbstract, Mixin1):
+ """Abstract class."""
+class Mixin2A:
+ """Mixin 2A."""
+class Mixin2B(Mixin2A):
+ """Mixin 2B."""
+class Concrete(Abstract, Mixin2B):
+ """Concrete class."""
+class SuperConcrete(Concrete):
+ """Super concrete class."""
+```
+
+//// tab | `TD` (or `TB`)
+
+```mermaid
+flowchart TD
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+////
+
+//// tab | `BT`
+
+```mermaid
+flowchart BT
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+////
+
+//// tab | `RL`
+
+```mermaid
+flowchart RL
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+////
+
+//// tab | `LR`
+
+```mermaid
+flowchart LR
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+////
+///
+
+[](){#option-preload_modules}
+## `preload_modules`
+
+- **:octicons-package-24: Type list [str ] | Noneyour_module
+Docstring of your module.
+their_object
+Docstring of their object.
+//// + +//// tab | Without preloaded modules +your_module
+Docstring of your module.
+//// +/// + +[](){#option-show_bases} +## `show_bases` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Show the base classes of a class. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_bases: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + show_bases: false +``` + +/// admonition | Preview + type: preview + +//// tab | With bases +SomeClass()
+Bases: SomeBaseClass
Docstring of the class.
+//// + +//// tab | Without bases +SomeClass()
+Docstring of the class.
+//// +/// + +[](){#option-show_inheritance_diagram} +## `show_inheritance_diagram` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Show the inheritance diagram of a class using [Mermaid](https://mermaid.js.org/). + +With this option enabled, an inheritance diagram (as a flowchart) +will be displayed after a class signature. +Each node will act as a cross-reference +and will bring you to the relevant class' documentation +when clicking on it. + +It should work out of the box with [Material for MkDocs][]. +For other themes, you must include Mermaid's Javascript code manually: + +```yaml title="mkdocs.yml" +extra_javascript: +- https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js +``` + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_inheritance_diagram: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + show_inheritance_diagram: false +``` + +/// admonition | Preview + type: preview + +With the following classes: + +```python +class SuperAbstract: + """Super abstract class.""" +class Mixin1: + """Mixin 1.""" +class Abstract(SuperAbstract, Mixin1): + """Abstract class.""" +class Mixin2A: + """Mixin 2A.""" +class Mixin2B(Mixin2A): + """Mixin 2B.""" +class Concrete(Abstract, Mixin2B): + """Concrete class.""" +class SuperConcrete(Concrete): + """Super concrete class.""" +``` + +The diagram for `SuperConcrete` will look like this: + +```mermaid +flowchart TD +SuperConcrete[SuperConcrete] +Concrete[Concrete] +Abstract[Abstract] +SuperAbstract[SuperAbstract] +Mixin1[Mixin1] +Mixin2B[Mixin2B] +Mixin2A[Mixin2A] + +Concrete --> SuperConcrete +Abstract --> Concrete +SuperAbstract --> Abstract +Mixin1 --> Abstract +Mixin2B --> Concrete +Mixin2A --> Mixin2B +``` + +*Nodes are not clickable in this example +because these classes do not exist in our documentation.* +/// + +[](){#option-show_source} +## `show_source` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Show the source code of this object. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_source: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + show_source: false +``` + +/// admonition | Preview + type: preview + +//// tab | With source +some_function()
+Docstring of the function.
+ +///// details | Source code in `package/module.py` + type: quote + +```python linenums="1" +def some_function(): + ... +``` +///// +//// + +//// tab | Without source +some_function()
+Docstring of the function.
+//// +/// + +[](){#option-skip_local_inventory} +## `skip_local_inventory` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to skip registering symbols in the objects inventory. + +With this option enabled, re-rendering docstrings for objects from external inventories is possible with their cross-references pointing to the original external inventory, not local. Similarly, it becomes possible to render the same symbol several times in the same documentation, with only one canonical location being used for cross-references (preventing confusion in mkdocs-autorefs). + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + skip_local_inventory: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + skip_local_inventory: true +``` + +/// admonition | Preview + type: preview + + +//// tab | Without `skip_local_inventory` + +```md exec="on" +::: bisect.bisect_left + options: + heading_level: 3 + skip_local_inventory: false + show_docstring_description: false +``` + +Notice how [`bisect.bisect_left`][] now points to the section above. + +//// + +//// tab | With `skip_local_inventory` + +```md exec="on" +::: bisect.bisect_right + inventories: + - https://docs.python.org/3/objects.inv + options: + heading_level: 3 + skip_local_inventory: true + show_docstring_description: false +``` + +Notice how [`bisect.bisect_right`][] points to the original Python documentation. + +//// +/// diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md new file mode 100644 index 00000000..593b6fb0 --- /dev/null +++ b/docs/usage/configuration/headings.md @@ -0,0 +1,810 @@ +# Headings options + +[](){#option-heading} +## `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. See also the [`toc_label` option][option-toc_label]. + +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" +``` + +[](){#option-heading_level} +## `heading_level` + +- **:octicons-package-24: Type [`int`][] :material-equal: `2`{ title="default value" }** + + +The initial heading level to use. + +When injecting documentation for an object, +the object itself and its members are rendered. +For each layer of objects, we increase the heading level by 1. + +The initial heading level will be used for the first layer. +If you set it to 3, then headings will start with ``.
+
+If the [heading for the root object][show_root_heading] is not shown,
+then the initial heading level is used for its members.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ heading_level: 2
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+ options:
+ heading_level: 3
+```
+
+/// admonition | Preview
+ type: preview
+
+//// tab | With level 3 and root heading
+module (3)
+
module (3)Docstring of the module.
+ClassA (4)
+Docstring of class A.
+ClassB (4)
+Docstring of class B.
+method_1 (5)
+Docstring of the method.
+//// + +//// tab | With level 3, without root heading +Docstring of the module.
+ClassA (3)
+Docstring of class A.
+ClassB (3)
+Docstring of class B.
+method_1 (4)
+Docstring of the method.
+//// +/// + +[](){#option-parameter_headings} +## `parameter_headings` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to render headings for function/method parameters. + +With this option enabled, each function/method parameter +(including parameters of `__init__` methods merged in their parent class +with the [`merge_init_into_class`][] option) +gets a permalink, an entry in the Table of Contents, +and an entry in the generated objects inventory (unless [`skip_local_inventory`][] is enabled). +The permalink and inventory entry allow cross-references +from internal and external pages. + +The identifier used in the permalink and inventory is of the following form: +`path.to.function(param_name)`. To manually cross-reference a parameter, +you can therefore use this Markdown syntax: + +```md +- Class parameter: [`param`][package.module.Class(param)] +- Method parameter: [`param`][package.module.Class.method(param)] +- Function parameter: [`param`][package.module.function(param)] +- Variadic positional parameters: [`*args`][package.module.function(*args)] +- Variadic keyword parameters: [`**kwargs`][package.module.function(**kwargs)] +``` + +Enabling this option along with [`signature_crossrefs`][] will automatically +render cross-references to parameters in class/function/method signatures +and attributes values. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + parameter_headings: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + parameter_headings: true +``` + +/// admonition | Preview: Cross-references + type: preview + +```md exec="on" +::: package.get_version + options: + heading_level: 3 + parameter_headings: true + docstring_section_style: list + +::: package.current_version + options: + heading_level: 3 + line_length: 100 +``` + +/// + +/// admonition | Preview: Parameter sections + type: preview + +//// tab | Table style +```md exec="on" +::: package.get_version + options: + heading_level: 3 + show_root_heading: false + show_root_toc_entry: false + parameter_headings: true + docstring_section_style: table + show_docstring_returns: false + show_docstring_description: false +``` +//// + +//// tab | List style +```md exec="on" +::: package.get_version + options: + heading_level: 3 + show_root_heading: false + show_root_toc_entry: false + parameter_headings: true + docstring_section_style: list + show_docstring_returns: false + show_docstring_description: false +``` +//// + +//// tab | Spacy style +```md exec="on" +::: package.get_version + options: + heading_level: 3 + show_root_heading: false + show_root_toc_entry: false + parameter_headings: true + docstring_section_style: spacy + show_docstring_returns: false + show_docstring_description: false +``` +//// +/// + +/// admonition | Preview: Table of contents (with symbol types) + type: preview + ++
ClassA (2)
+Docstring of class A.
+method_a1 (3)
+Docstring of the method.
+ClassB (2)
+Docstring of class B.
+method_b1 (3)
+Docstring of the method.
+//// + +//// tab | Without root heading +Docstring of class A.
+method_a1 (2)
+Docstring of the method.
+Docstring of class B.
+method_b1 (2)
+Docstring of the method.
+//// +/// + +[](){#option-show_root_toc_entry} +## `show_root_toc_entry` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +If the root heading is not shown, at least add a ToC entry for it. + +If you inject documentation for an object in the middle of a page, +after long paragraphs, and without showing the [root heading][show_root_heading], +then you will not be able to link to this particular object +as it won't have a permalink and will be "lost" in the middle of text. +In that case, it is useful to add a hidden anchor to the document, +which will also appear in the table of contents. + +In other cases, you might want to disable the entry to avoid polluting the ToC. +It is not possible to show the root heading *and* hide the ToC entry. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_root_toc_entry: true +``` + +```md title="or in docs/some_page.md (local configuration)" +## Some heading + +Lots of text. + +::: path.to.object + options: + show_root_toc_entry: false + +## Other heading. + +More text. +``` + +/// admonition | Preview + 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" } +//// + +//// tab | Without ToC entry +**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" } +//// +/// + +[](){#option-show_root_full_path} +## `show_root_full_path` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Show the full Python path for the root object heading. + +The path of a Python object is the dot-separated list of names +under which it is accessible, for example `package.module.Class.method`. + +With this option you can choose to show the full path of the object +you inject documentation for, or just its name. This option impacts +only the object you specify, not its members. For members, see the two +other options [`show_root_members_full_path`][] +and [`show_object_full_path`][]. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_root_full_path: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: package.module.Class.method + options: + show_root_full_path: false +``` + +/// admonition | Preview + type: preview + +//// tab | With root full path +package.module.Class.method
+Docstring of the method.
+//// + +//// tab | Without root full path +method
+Docstring of the method.
+//// +/// + +[](){#option-show_root_members_full_path} +## `show_root_members_full_path` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Show the full Python path of the root members. + +This option does the same thing as [`show_root_full_path`][], +but for direct members of the root object instead of the root object itself. + +To show the full path for every member recursively, +see [`show_object_full_path`][]. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_root_members_full_path: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: package.module + options: + show_root_members_full_path: false +``` + +/// admonition | Preview + type: preview + +//// tab | With members full path +Docstring of the module.
+package.module.Class
+Docstring of the class.
+method
+Docstring of the method.
+//// + +//// tab | Without members full path +Docstring of the module.
+Class
+Docstring of the class.
+method
+Docstring of the method.
+//// +/// + +[](){#option-show_object_full_path} +## `show_object_full_path` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +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 +[`show_root_members_full_path`][]: + +`show_root_members_full_path` | `show_object_full_path` | Direct root members path +----------------------------- | ----------------------- | ------------------------ +False | False | Name only +False | True | Full +True | False | Full +True | True | Full + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_object_full_path: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: package.module + options: + show_object_full_path: false +``` + +/// admonition | Preview + type: preview + +//// tab | With objects full path +Docstring of the module.
+package.module.Class
+Docstring of the class.
+package.module.Class.method
+Docstring of the method.
+//// + +//// tab | Without objects full path +Docstring of the module.
+Class
+Docstring of the class.
+method
+Docstring of the method.
+//// +/// + +[](){#option-show_category_heading} +## `show_category_heading` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +When [grouped by categories][group_by_category], show a heading for each category. +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 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 +using H6 headings, which might decrease the readability +of your API docs. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + group_by_category: true + show_category_heading: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: package.module + options: + group_by_category: true + show_category_heading: false +``` + +/// admonition | Preview + type: preview + +//// tab | With category headings +Docstring of the module.
+Attributes (2)
+module_attribute (3)
+Docstring of the module attribute.
+Classes (2)
+Class (3)
+Docstring of the class.
+Attributes (4)
+class_attribute (5)
+Docstring of the class attribute.
+Methods (4)
+method (5)
+Docstring of the method.
+//// + +//// tab | Without category headings +Docstring of the module.
+module_attribute (2)
+Docstring of the module attribute.
+Class (2)
+Docstring of the class.
+class_attribute (3)
+Docstring of the class attribute.
+method (3)
+Docstring of the method.
+//// +/// + +[](){#option-show_symbol_type_heading} +## `show_symbol_type_heading` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Show the symbol type in headings. + +This option will prefix headings with +module
+Docstring of the module.
+attribute
+Docstring of the module attribute.
+function
+Docstring of the function.
+Class
+Docstring of the class.
+method
+Docstring of the method.
+//// + +//// tab | Without symbol type in headings +module
+Docstring of the module.
+attribute
+Docstring of the module attribute.
+function
+Docstring of the function.
+Class
+Docstring of the class.
+method
+Docstring of the method.
+//// +/// + +[](){#option-show_symbol_type_toc} +## `show_symbol_type_toc` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Show the symbol type in the Table of Contents. + +This option will prefix items in the ToC with +-
+
module
+ attribute
+ function
+ Class +-
+
method
+
+
-
+
- module +
- attribute +
- function +
- Class
+
-
+
- method +
+
+
list [str ] |
+ bool | NoneModule docstring.
+this_function
+Function docstring.
+ThisClass
+Class docstring.
+method
+Method docstring.
+this_attribute
+Attribute docstring.
+//// + +//// tab | With `members: false` or `members: []` +Module docstring.
+//// + +//// tab | With `members: [ThisClass]` +Module docstring.
+ThisClass
+Class docstring.
+method
+Method docstring.
+//// +/// + +INFO: **The default behavior (with unspecified `members` or `members: null`) is to use [`filters`][].** + +[](){#option-inherited_members} +## `inherited_members` + +- **:octicons-package-24: Typelist [str ] |
+ bool Module docstring.
+Base
+Base class.
+base
+Base method.
+Main
+Main class.
+base
+Base method.
+main
+Main method.
+//// + +//// tab | Without inherited members +Module docstring.
+Base
+Base class.
+base
+Base method.
+Main
+Main class.
+main
+Main method.
+//// + +/// + +[](){#option-members_order} +## `members_order` + +- **:octicons-package-24: Type `str | list[str]` :material-equal: `"alphabetical"`{ title="default value" }** + + +The members ordering to use. Possible values: + +- `__all__`: Order according to `__all__` attributes. Since classes do not define `__all__` attributes, you can specify a second ordering method by using a list. +- `alphabetical`: Order by the members names. +- `source`: Order members as they appear in the source file. + +The order applies for all members, recursively. +The order will be ignored for members that are explicitely sorted using the [`members`][] option. +**Note that members will still be grouped by category, +according to the [`group_by_category`][] option.** + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + members_order: alphabetical +``` + +```md title="or in docs/some_page.md (local configuration)" +::: package.module + options: + members_order: source +``` + +```md title="or in docs/some_page.md (local configuration)" +::: package.module + options: + members_order: [__all__, source] +``` + +```python title="package/module.py" +"""Module docstring.""" + + +def function_b(): + """Function a.""" + + +def function_a(): + """Function b.""" + + +def function_c(): + """Function c.""" +``` + +/// admonition | Preview + type: preview + +//// tab | With alphabetical order +Module docstring.
+function_a
+Function a.
+function_b
+Function b.
+function_c
+Function c.
+//// + +//// tab | With source order +Module docstring.
+function_b
+Function b.
+function_a
+Function a.
+function_c
+Function c.
+//// +/// + +[](){#option-filters} +## `filters` + +- **:octicons-package-24: Typelist [str ] | Literal ["public"] | NoneModule docstring.
+hello
+Function docstring.
+_world
+Function docstring.
+//// + +//// tab | With `filters: ["hello"]` +Module docstring.
+hello
+Function docstring.
+//// + +//// tab | With `filters: ["!hello"]` +Module docstring.
+_world
+Function docstring.
+//// +/// + +/// admonition | Common filters + type: tip + +Here are some common filters that you might to want to use. + +- `["!^_"]`: exclude all private/protected/special objects +- `["!^_", "^__init__$"]`: same as above, but keep `__init__` methods +- `["!^_[^_]"]`: exclude all private/protected objects, keep special ones (default filters) +/// + +[](){#option-group_by_category} +## `group_by_category` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Group the object members by categories: attributes, classes, functions, and modules. + +Members within a same category will be ordered according to the [`members_order`][] option. +You can use the [`show_category_heading`][] option to also render a heading for each category. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + group_by_category: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: package.module + options: + group_by_category: false +``` + +```python title="package/module.py" +def function_a(): + ... + + +class ClassB: + ... + + +attribute_C = 0 + + +def function_d(): + ... +``` + +/// admonition | Preview + type: preview + +//// tab | With category grouping +Module docstring.
+attribute_c
+Attribute docstring.
+ClassB
+Class docstring.
+function_a
+Function docstring.
+function_d
+Function docstring.
+//// + +//// tab | Without category grouping +Module docstring.
+function_a
+Function docstring.
+ClassB
+Class docstring.
+attribute_c
+Attribute docstring.
+function_d
+Function docstring.
+//// +/// + +[](){#option-show_submodules} +## `show_submodules` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +When rendering a module, show its submodules recursively. + +This is false by default, because most of the time we render only one module per page, +and when rendering a package (a tree of modules and their members) on a single page, +we quickly run out of [heading levels][heading_level]. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_submodules: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: package.subpackage + options: + show_submodules: false +``` + +```tree title="package" +package + __init__.py + subpackage + __init__.py + submodule.py +``` + +/// admonition | Preview + type: preview + +//// tab | With submodules +Subpackage docstring.
+subpackage_member
+Member docstring.
+submodule
+Submodule docstring.
+submodule_member
+Member docstring.
+//// + +//// tab | Without submodules +Subpackage docstring.
+subpackage_member
+Member docstring.
+//// +/// + +[](){#option-summary} +## `summary` + +- **:octicons-package-24: Typebool | dict [str , bool ]MyClass
+Class docstring.
+Methods:
+-
+
- my_method1: Summary of the method (first docstring line). +
- my_method2: Summary of the method (first docstring line). +
Attributes:
+-
+
- attr1: Summary of the attribute (first docstring line). +
- attr2: Summary of the attribute (first docstring line). +
MyClass
+Class docstring.
+Methods:
+-
+
- my_method1: Summary of the method (first docstring line). +
- my_method2: Summary of the method (first docstring line). +
+ some_attr:
+ int
+
+instance-attribute
+////
+
+//// tab | Without labels
+
+ some_attr:
+ int
+
+////
+///
diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md
new file mode 100644
index 00000000..109362e3
--- /dev/null
+++ b/docs/usage/configuration/signatures.md
@@ -0,0 +1,701 @@
+# Signatures options
+
+[](){#option-annotations_path}
+## `annotations_path`
+
+- **:octicons-package-24: Type [`str`][] :material-equal: `"brief"`{ title="default value" }**
+
+
+The verbosity for annotations path.
+
+Possible values:
+
+- `brief` (recommended): render only the last component of each type path, not their full paths.
+ For example, it will render `Sequence[Path]` and not `typing.Sequence[pathlib.Path]`.
+ Brief annotations will cross-reference the right object anyway,
+ and show the full path in a tooltip when hovering them.
+- `source`: render annotations as written in the source. For example if you imported `typing` as `t`,
+ it will render `typing.Sequence` as `t.Sequence`. Each part will cross-reference the relevant object:
+ `t` will link to the `typing` module and `Sequence` will link to the `Sequence` type.
+- `full`: render annotations with their full path (the opposite of brief).
+ For example if you import `Sequence` and `Pattern` from `typing` and annoate something using
+ `Sequence[Pattern]`, it will render as `typing.Sequence[typing.Pattern]`, with each part
+ cross-referencing the corresponding object.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ annotations_path: brief
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+ options:
+ annotations_path: source
+```
+
+
+/// admonition | Preview
+ type: preview
+
+//// tab | Brief annotations
+```python
+import markdown
+import markupsafe
+
+
+def convert(text: str, md: markdown.Markdown) -> markupsafe.Markup:
+ """Convert text to Markdown.
+
+ Parameters:
+ text: The text to convert.
+ md: A Markdown instance.
+
+ Returns:
+ Converted markup.
+ """
+ return markupsafe.Markup(md.convert(text))
+```
+
+convert(text, md)
+Convert text to Markdown.
+Parameters:
+ +**Type** | **Description** | **Default** +---------- | ------------------------ | ----------- +[`str`][] | The text to convert. | *required* +[`Markdown`](#ref-to-markdown){ .external title="markdown.Markdown" } | A Markdown instance. | *required* + +Returns:
+ +**Type** | **Name** | **Description** +---------- | ----------- | --------------- +[`Markup`](#ref-to-markup){ .external title="markupsafe.Markup" } | `text` | Converted markup. +//// + +//// tab | Source annotations +```python +import markdown +from markupsafe import Markup + + +def convert(text: str, md: markdown.Markdown) -> Markup: + """Convert text to Markdown. + + Parameters: + text: The text to convert. + md: A Markdown instance. + + Returns: + Converted markup. + """ + return Markup(md.convert(text)) +``` + +convert(text, md)
+Convert text to Markdown.
+Parameters:
+ +**Type** | **Description** | **Default** +---------- | ------------------------ | ----------- +[`str`][] | The text to convert. | *required* +markdown.Markdown | A Markdown instance. | *required*
+
+Returns:
+ +**Type** | **Name** | **Description** +---------- | ----------- | --------------- +[`Markup`](#ref-to-markup){ .external title="markupsafe.Markup" } | `text` | Converted markup. +//// + +//// tab | Full annotations +```python +from markdown import Markdown +from markupsafe import Markup + + +def convert(text: str, md: Markdown) -> Markup: + """Convert text to Markdown. + + Parameters: + text: The text to convert. + md: A Markdown instance. + + Returns: + Converted markup. + """ + return Markup(md.convert(text)) +``` + +convert(text, md)
+Convert text to Markdown.
+Parameters:
+ +**Type** | **Description** | **Default** +---------- | ------------------------ | ----------- +[`str`][] | The text to convert. | *required* +markdown.Markdown | A Markdown instance. | *required*
+
+Returns:
+ +**Type** | **Name** | **Description** +---------- | ----------- | --------------- +markupsafe.Markup | `text` | Converted markup.
+////
+///
+
+[](){#option-line_length}
+## `line_length`
+
+- **:octicons-package-24: Type [`int`][] :material-equal: `60`{ title="default value" }**
+
+
+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 a formatter and
+the specified line length.
+
+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:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ separate_signature: true
+ line_length: 60
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+ options:
+ separate_signature: true
+ line_length: 80
+```
+
+/// admonition | Preview
+ type: preview
+
+//// tab | Line length 60
+long_function_name
+long_function_name(
+ long_parameter_1="hello",
+ long_parameter_2="world",
+)long_function_name
+long_function_name(long_parameter_1="hello", long_parameter_2="world")function
+ +```python +@overload +function(param1: int): ... +@overload +function(param1: str): ... +``` +Function docstring. + +//// +//// tab | Without overloads only +function
+ +```python +@overload +function(param1: int): ... +@overload +function(param1: str): ... +function(param1: str | int) +``` +Function docstring. + +//// + +/// + +[](){#option-show_signature} +## `show_signature` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Show methods and functions signatures. + +Without it, just the function/method name is rendered. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_signature: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_signature: false +``` + +/// admonition | Preview + type: preview + +//// tab | With signature +function(param1, param2=None)
+Function docstring.
+//// + +//// tab | Without signature +function
+Function docstring.
+//// +/// + +[](){#option-show_signature_annotations} +## `show_signature_annotations` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Show the type annotations in methods and functions signatures. + +Since the heading can become quite long when annotations are rendered, +it is usually best to [separate the signature][separate_signature] from the heading. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + separate_signature: true + show_signature_annotations: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + separate_signature: true + show_signature_annotations: false +``` + +/// admonition | Preview + type: preview + +//// tab | With signature annotations +function
+ +```python +function( + param1: list[int | float], + param2: bool | None = None, +) -> float +``` + +Function docstring.
+//// + +//// tab | Without signature annotations +function
+ +```python +function(param1, param2=None) +``` + +Function docstring.
+//// +/// + +[](){#option-show_signature_type_parameters} +## `show_signature_type_parameters` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Show the type parameters in generic classes, methods, functions and type aliases +signatures. + +Since the heading can become quite long when type parameters are rendered, it is +usually best to [separate the signature][separate_signature] from the heading. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + separate_signature: true + show_signature_annotations: true + show_signature_type_parameters: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + separate_signature: true + show_signature_annotations: true + show_signature_type_parameters: false +``` + +/// admonition | Preview + type: preview + +//// tab | With signature type parameters +function
+ +```python +function[T, *R](param: T) -> tuple[*R] +``` + +Function docstring.
+//// + +//// tab | Without signature type parameters +function
+ +```python +function(param: T) -> tuple[*R] +``` + +Function docstring.
+//// +/// + +[](){#option-separate_signature} +## `separate_signature` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +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 a formatter and +the specified [line length][line_length]. + +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: +- mkdocstrings: + handlers: + python: + options: + separate_signature: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + separate_signature: true +``` + +/// admonition | Preview + type: preview + +//// tab | With separate signature +function
+ +```python +function(param1, param2=None) +``` + +Function docstring.
+//// + +//// tab | Without separate signature +function(param1, param2=None)
+Function docstring.
+//// +/// + +[](){#option-show_attribute_values} +## `show_attribute_values` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Show initial values of attributes in classes. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_attribute_values: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + show_attribute_values: true +``` + +```python title="package/module.py" +class SomeClass: + def __init__(self): + self.some_attr = 1 +``` + +/// admonition | Preview + type: preview + +//// tab | With attribute values visible +SomeClass
+some_attr = 1
+//// + +//// tab | With attribute values hidden +SomeClass
+some_attr
+//// +/// + +[](){#option-show_overloads} +## `show_overloads` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + +Whether to render function / method overloads. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_overloads: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_overloads: false +``` + +/// admonition | Preview + type: preview +//// tab | With overloads +function
+ + +```python +@overload +function(param1: int): ... + +@overload +function(param1: str): ... + +function(param1: str | int) +``` +Function docstring. + +//// +//// tab | Without overloads +function
+ +```python +function(param1: str | int) +``` +Function docstring. + +//// +/// + +[](){#option-signature_crossrefs} +## `signature_crossrefs` + +Whether to render cross-references for type annotations in signatures. + +When signatures are separated from headings with the [`separate_signature`][] option +and type annotations are shown with the [`show_signature_annotations`][] option, +this option will render a cross-reference (link) for each type annotation in the signature. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + separate_signature: true + show_signature_annotations: true + signature_crossrefs: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + separate_signature: true + show_signature_annotations: true + signature_crossrefs: true +``` + +/// admonition | Preview + type: preview + +//// tab | With signature cross-references +do_format_code
+ +Function docstring.
+//// + +//// tab | Without signature cross-references +do_format_code
+do_format_code(code: str, line_length: int) -> str
+Function docstring.
+//// +/// + +[](){#option-unwrap_annotated} +## `unwrap_annotated` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to unwrap [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated){ .external } +types to show only the type without the annotations. + +For example, unwrapping `Annotated[int, Gt(10)]` will render `int`. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + unwrap_annotated: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + unwrap_annotated: true +``` diff --git a/docs/usage/customization.md b/docs/usage/customization.md new file mode 100644 index 00000000..d1e66b31 --- /dev/null +++ b/docs/usage/customization.md @@ -0,0 +1,496 @@ +# Customization + +It is possible to customize the output of the generated documentation with CSS +and/or by overriding templates. + +## CSS classes + +Our templates add [CSS](https://www.w3schools.com/Css/) classes to many HTML elements +to make it possible for users to customize the resulting look and feel. + +To add CSS rules and style mkdocstrings' output, +put them in a CSS file in your docs folder, for example in `docs/css/mkdocstrings.css`, +and reference this file in [MkDocs' `extra_css` configuration option](https://www.mkdocs.org/user-guide/configuration/#extra_css): + +```yaml title="mkdocs.yml" +extra_css: +- css/mkdocstrings.css +``` + +Example: + +```css title="docs/css/mkdocstrings.css" +.doc-section-title { + font-weight: bold; +} +``` + +The following CSS classes are used in the generated HTML: + +- `doc`: on all the following elements +- `doc-children`: on `div`s containing the children of an object +- `doc-object`: on `div`s containing an object + - `doc-attribute`: on `div`s containing an attribute + - `doc-class`: on `div`s containing a class + - `doc-function`: on `div`s containing a function + - `doc-module`: on `div`s containing a module + - `doc-type_alias`: on `div`s containing a type alias +- `doc-heading`: on objects headings + - `doc-object-name`: on `span`s wrapping objects names/paths in the heading + - `doc-KIND-name`: as above, specific to the kind of object (module, class, function, attribute, type_alias) +- `doc-contents`: on `div`s wrapping the docstring then the children (if any) + - `first`: same, but only on the root object's contents `div` +- `doc-labels`: on `span`s wrapping the object's labels + - `doc-label`: on `small` elements containing a label + - `doc-label-LABEL`: same, where `LABEL` is replaced by the actual label +- `doc-section-title`: on section titles (depend on the [selected style for section rendering][docstring_style]) +- `doc-section-item`: on section items (depend on the [selected style for section rendering][docstring_style]) +- `doc-md-description`: on `div`s containing HTML descriptions converted from Markdown docstrings +- `doc-symbol`: on `code` tags of symbol types + - `doc-symbol-heading`: on symbol types in headings + - `doc-symbol-toc`: on symbol types in the ToC + - `doc-symbol-KIND`: specific to the kind of object (`module`, `class`, `function`, `method`, `attribute`, `type_alias`) + +/// admonition | Example with colorful labels + type: example + +//// tab | CSS +```css +.doc-label { border-radius: 15px; padding: 2px 8px; font-weight: bold; } +.doc-label-special { background-color: #3330E4; color: white; } +.doc-label-private { background-color: #F637EC; color: white; } +.doc-label-property { background-color: #FBB454; color: black; } +.doc-label-read-only { background-color: #FAEA48; color: black; } +``` +//// + +//// tab | Result + ++
+ special + private + property + read-only +
+ +//// + +/// + +## Symbol types + +### Colors + +You can customize the colors of the symbol types +(see [`show_symbol_type_heading`][show_symbol_type_heading] and [`show_symbol_type_toc`][show_symbol_type_toc]) +by overriding the values of our CSS variables, for example: + +```css title="docs/css/mkdocstrings.css" +[data-md-color-scheme="default"] { + --doc-symbol-parameter-fg-color: #df50af; + --doc-symbol-type_parameter-fg-color: #df50af; + --doc-symbol-attribute-fg-color: #0079ff; + --doc-symbol-function-fg-color: #00dfa2; + --doc-symbol-method-fg-color: #00dfa2; + --doc-symbol-class-fg-color: #d1b619; + --doc-symbol-type_alias-fg-color: #d1b619; + --doc-symbol-module-fg-color: #ff0060; + + --doc-symbol-parameter-bg-color: #df50af1a; + --doc-symbol-type_parameter-bg-color: #df50af1a; + --doc-symbol-attribute-bg-color: #0079ff1a; + --doc-symbol-function-bg-color: #00dfa21a; + --doc-symbol-method-bg-color: #00dfa21a; + --doc-symbol-class-bg-color: #d1b6191a; + --doc-symbol-type_alias-bg-color: #d1b6191a; + --doc-symbol-module-bg-color: #ff00601a; +} + +[data-md-color-scheme="slate"] { + --doc-symbol-parameter-fg-color: #ffa8cc; + --doc-symbol-type_parameter-fg-color: #ffa8cc; + --doc-symbol-attribute-fg-color: #963fb8; + --doc-symbol-function-fg-color: #6d67e4; + --doc-symbol-method-fg-color: #6d67e4; + --doc-symbol-class-fg-color: #46c2cb; + --doc-symbol-type_alias-fg-color: #46c2cb; + --doc-symbol-module-fg-color: #f2f7a1; + + --doc-symbol-parameter-bg-color: #ffa8cc1a; + --doc-symbol-type_parameter-bg-color: #ffa8cc1a; + --doc-symbol-attribute-bg-color: #963fb81a; + --doc-symbol-function-bg-color: #6d67e41a; + --doc-symbol-method-bg-color: #6d67e41a; + --doc-symbol-class-bg-color: #46c2cb1a; + --doc-symbol-type_alias-bg-color: #46c2cb1a; + --doc-symbol-module-bg-color: #f2f7a11a; +} +``` + +The `[data-md-color-scheme="*"]` selectors work with the [Material for MkDocs] theme. +If you are using another theme, adapt the selectors to this theme +if it supports light and dark themes, +otherwise just override the variables at root level: + +```css title="docs/css/mkdocstrings.css" +:root { + --doc-symbol-parameter-fg-color: #df50af; + --doc-symbol-type_parameter-fg-color: #df50af; + --doc-symbol-attribute-fg-color: #0079ff; + --doc-symbol-function-fg-color: #00dfa2; + --doc-symbol-method-fg-color: #00dfa2; + --doc-symbol-class-fg-color: #d1b619; + --doc-symbol-type_alias-fg-color: #d1b619; + --doc-symbol-module-fg-color: #ff0060; + + --doc-symbol-parameter-bg-color: #df50af1a; + --doc-symbol-type_parameter-bg-color: #df50af1a; + --doc-symbol-attribute-bg-color: #0079ff1a; + --doc-symbol-function-bg-color: #00dfa21a; + --doc-symbol-method-bg-color: #00dfa21a; + --doc-symbol-class-bg-color: #d1b6191a; + --doc-symbol-type_alias-bg-color: #d1b6191a; + --doc-symbol-module-bg-color: #ff00601a; +} +``` + +/// admonition | Preview + type: preview + +
+
+
+
+///
+
+### Names
+
+You can also change the actual symbol names.
+For example, to use single letters instead of truncated types:
+
+```css title="docs/css/mkdocstrings.css"
+.doc-symbol-parameter::after {
+ content: "P";
+}
+
+.doc-symbol-type_parameter::after {
+ content: "P";
+}
+
+.doc-symbol-attribute::after {
+ content: "A";
+}
+
+.doc-symbol-function::after {
+ content: "F";
+}
+
+.doc-symbol-method::after {
+ content: "M";
+}
+
+.doc-symbol-class::after {
+ content: "C";
+}
+
+.doc-symbol-type_alias::after {
+ content: "T";
+}
+
+.doc-symbol-module::after {
+ content: "M";
+}
+```
+
+/// admonition | Preview
+ type: preview
+
+
+ Try cycling through the themes to see the colors for each theme:
+
+
+
+
+
+
+
+
+
+
+///
+
+## Templates
+
+Templates are organized into the following tree:
+
+```python exec="1" result="tree"
+from pathlib import Path
+
+basedir = "src/mkdocstrings_handlers/python/templates/material"
+print("theme/")
+for filepath in sorted(path for path in Path(basedir).rglob("*") if "_base" not in str(path) and path.suffix != ".css"):
+ print(
+ " " * (len(filepath.relative_to(basedir).parent.parts) + 1)
+ + filepath.name
+ + ("/" if filepath.is_dir() else "")
+ )
+```
+
+See them [in the repository](https://github.com/mkdocstrings/python/tree/main/src/mkdocstrings_handlers/python/templates/).
+See the general *mkdocstrings* documentation to learn how to override them: https://mkdocstrings.github.io/theming/#templates.
+
+Each one of these templates extends a base version in `theme/_base`. Example:
+
+```html+jinja title="theme/class.html"
+{% extends "_base/class.html" %}
+```
+
+Some of these templates define [Jinja blocks](https://jinja.palletsprojects.com/en/3.0.x/templates/#template-inheritance).
+allowing to customize only *parts* of a template
+without having to fully copy-paste it into your project:
+
+```jinja title="templates/theme/class.html"
+{% extends "_base/class.html" %}
+{% block contents %}
+ {{ block.super }}
+ Additional contents
+{% endblock contents %}
+```
+
+### Available blocks
+
+Only the templates for the **Material for MkDocs** provide Jinja blocks.
+The following tables show the block names, description,
+and the Jinja context available in their scope.
+
+#### `module.html`
+
+- `heading`: The module heading.
+- `labels`: The module labels.
+- `contents`: The module contents: docstring and children blocks.
+- `docstring`: The module docstring.
+- `summary`: The automatic summaries of members.
+- `children`: The module children.
+
+Available context:
+
+- `config`: The handler configuration (dictionary).
+- `module`: The [Module][griffe.Module] instance.
+
+#### `type_alias.html`
+
+- `heading`: The class heading.
+- `labels`: The class labels.
+- `signature`: The class signature.
+- `contents`: The class contents: bases, docstring, source and children blocks.
+- `docstring`: The class docstring.
+
+Available context:
+
+- `config`: The handler configuration (dictionary).
+- `type_alias`: The [TypeAlias][griffe.TypeAlias] instance.
+
+#### `class.html`
+
+- `heading`: The class heading.
+- `labels`: The class labels.
+- `signature`: The class signature.
+- `contents`: The class contents: bases, docstring, source and children blocks.
+- `bases`: The class bases.
+- `docstring`: The class docstring.
+- `summary`: The automatic summaries of members.
+- `source`: The class source code.
+- `children`: The class children.
+
+Available context:
+
+- `config`: The handler configuration (dictionary).
+- `class`: The [Class][griffe.Class] instance.
+
+#### `function.html`
+
+- `heading`: The function heading.
+- `labels`: The function labels.
+- `signature`: The function signature.
+- `contents`: The function contents: docstring and source blocks.
+- `docstring`: The function docstring.
+- `source`: The function source code.
+
+Available context:
+
+- `config`: The handler configuration (dictionary).
+- `function`: The [Function][griffe.Function] instance.
+
+#### `attribute.html`
+
+- `heading`: The attribute heading.
+- `labels`: The attribute labels.
+- `signature`: The attribute signature.
+- `contents`: The attribute contents: docstring block.
+- `docstring`: The attribute docstring.
+
+Available context:
+
+- `config`: The handler configuration (dictionary).
+- `attribute`: The [Attribute][griffe.Attribute] instance.
+
+#### Docstring sections
+
+In `docstring/attributes.html`,
+`docstring/functions.html`,
+`docstring/classes.html`,
+`docstring/modules.html`,
+`docstring/other_parameters.html`,
+`docstring/parameters.html`,
+`docstring/raises.html`,
+`docstring/receives.html`,
+`docstring/returns.html`,
+`docstring/type_aliases.html`,
+`docstring/type_parameters.html`,
+`docstring/warns.html`,
+and `docstring/yields.html`:
+
+- `table_style`: The section as a table.
+- `list_style`: The section as a list.
+- `spacy_style`: The section as a Spacy table.
+
+Available context:
+
+- `section`: The [DocstringSection][griffe.DocstringSection] instance (see `DocstringSection*` subclasses).
+
+### Syntax highlight in signatures
+
+You can customize the colors in syntax highlighted signatures.
+If you are using the [Material for MkDocs] theme,
+here are some customization examples:
+
+```css
+/* Fancier color for operators such as * and |. */
+.doc-signature .o {
+ color: var(--md-code-hl-special-color);
+}
+
+/* Fancier color for constants such as None, True, and False. */
+.doc-signature .kc {
+ color: var(--md-code-hl-constant-color);
+}
+
+/* Fancier color for built-in types (only useful when cross-references are used). */
+.doc-signature .n > a[href^="https://docs.python.org/"][href*="/functions.html#"],
+.doc-signature .n > a[href^="https://docs.python.org/"][href*="/stdtypes.html#"] {
+ color: var(--md-code-hl-constant-color);
+}
+```
+
+For other themes, use their own CSS variables,
+or use plain colors such as `violet` or `#2987f2`.
+
+## Style recommendations
+
+[](){#recommended-style-material}
+### Material
+
+Here are some CSS rules for the [Material for MkDocs] theme:
+
+```css
+--8<-- "docs/css/mkdocstrings.css"
+```
+
+[](){#recommended-style-readthedocs}
+### ReadTheDocs
+
+Here are some CSS rules for the built-in ReadTheDocs theme:
+
+```css
+/* Indentation. */
+div.doc-contents:not(.first) {
+ padding-left: 25px;
+ border-left: .05rem solid rgba(200, 200, 200, 0.2);
+}
+```
diff --git a/docs/usage/docstrings/google.md b/docs/usage/docstrings/google.md
new file mode 100644
index 00000000..1c843a3b
--- /dev/null
+++ b/docs/usage/docstrings/google.md
@@ -0,0 +1,28 @@
+# Google style
+
+## :warning: Work in Progress!
+
+### Google-style admonitions
+
+With Google-style docstrings, any section that is not recognized will be transformed into its admonition equivalent.
+For example:
+
+=== "Docstring"
+ ```python
+ """
+ Note:
+ It looks like a section, but it will be rendered as an admonition.
+
+ Tip: You can even choose a title.
+ 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.**
+ This admonition has a custom title!
+
+See [Napoleon's documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/).
diff --git a/docs/usage/docstrings/numpy.md b/docs/usage/docstrings/numpy.md
new file mode 100644
index 00000000..524bfbfe
--- /dev/null
+++ b/docs/usage/docstrings/numpy.md
@@ -0,0 +1,11 @@
+# Numpydoc style
+
+## :warning: Work in Progress!
+
+NOTE: As Numpy-style is partially supported by the underlying parser,
+you may experience problems in the building process if your docstring
+has a `Methods` section in the class docstring
+(see [#366](https://github.com/mkdocstrings/mkdocstrings/issues/366)).
+
+See [Numpydoc's documentation](https://numpydoc.readthedocs.io/en/latest/format.html).
+See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/).
diff --git a/docs/usage/docstrings/sphinx.md b/docs/usage/docstrings/sphinx.md
new file mode 100644
index 00000000..bf88c19b
--- /dev/null
+++ b/docs/usage/docstrings/sphinx.md
@@ -0,0 +1,6 @@
+# Sphinx style
+
+## :warning: Work in Progress!
+
+See [Sphinx's documentation](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html).
+See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/).
diff --git a/docs/usage/extensions.md b/docs/usage/extensions.md
new file mode 100644
index 00000000..4f6b96b3
--- /dev/null
+++ b/docs/usage/extensions.md
@@ -0,0 +1,17 @@
+# Extensions
+
+## :warning: Work in Progress!
+
+The Python handler supports extensions through
+[*mkdocstrings*' handler extensions](https://mkdocstrings.github.io/usage/handlers/#handler-extensions).
+
+Specifically, additional templates can be added to the handler,
+and Griffe extensions can instruct the handler to use a particular template
+for a particular object by setting a value in the Griffe object's `extra` dictionary:
+
+```python title="griffe_extension.py"
+obj = ... # get a reference to a Griffe object
+if "mkdocstrings" not in obj.extra:
+ obj.extra["mkdocstrings"] = {}
+obj.extra["mkdocstrings"]["template"] = "template_name.html"
+```
diff --git a/docs/usage/index.md b/docs/usage/index.md
new file mode 100644
index 00000000..3348a627
--- /dev/null
+++ b/docs/usage/index.md
@@ -0,0 +1,486 @@
+# Usage
+
+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).
+
+## Installation
+
+You can install this handler as a *mkdocstrings* extra:
+
+```toml title="pyproject.toml"
+# PEP 621 dependencies declaration
+# adapt to your dependencies manager
+[project]
+dependencies = [
+ "mkdocstrings[python]>=0.18",
+]
+```
+
+You can also explicitly depend on the handler:
+
+```toml title="pyproject.toml"
+# PEP 621 dependencies declaration
+# adapt to your dependencies manager
+[project]
+dependencies = [
+ "mkdocstrings-python",
+]
+```
+
+The Python handler is the default *mkdocstrings* handler.
+You can change the default handler,
+or explicitely set the Python handler as default by defining the `default_handler`
+configuration option of `mkdocstrings` in `mkdocs.yml`:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+ default_handler: python
+```
+
+## Injecting documentation
+
+With the Python handler installed and configured as default handler,
+you can inject documentation for a module, class, function, or any other Python object
+with *mkdocstrings*' [autodoc syntax], in your Markdown pages:
+
+```md
+::: path.to.object
+```
+
+If another handler was defined as default handler,
+you can explicitely ask for the Python handler to be used when injecting documentation
+with the `handler` option:
+
+```md
+::: path.to.object
+ handler: python
+```
+
+## Configuration
+
+When installed, the Python handler becomes the default *mkdocstrings* handler.
+You can configure it in `mkdocs.yml`:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ ... # the Python handler configuration
+```
+
+### Global-only options
+
+Some options are **global only**, and go directly under the handler's name.
+
+[](){#setting-inventories}
+#### `inventories`
+
+This option is used to load Sphinx-compatible objects inventories from other
+documentation sites. For example, you can load the standard library
+objects inventory like this:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ inventories:
+ - https://docs.python.org/3/objects.inv
+```
+
+When loading 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 load
+the inventories of your project's dependencies, at least those
+that are used in the public API.
+
+See [*mkdocstrings*' documentation on inventories][inventories]
+for more details.
+
+ [inventories]: https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories
+
+Additionally, the Python handler accepts a `domains` option in the inventory options,
+which allows to select the inventory domains to load.
+By default the Python handler only selects the `py` domain (for Python objects).
+You might find useful to also enable the [`std` domain][std domain]:
+
+ [std domain]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-standard-domain
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ inventories:
+ - url: https://docs.python-requests.org/en/master/objects.inv
+ domains: [std, py]
+```
+
+[](){#setting-load_external_modules}
+#### `load_external_modules`
+
+This option allows resolving aliases (imports) to any external module.
+Modules are considered external when they are not part
+of the package your are injecting documentation for.
+Setting this option to `True` will tell the handler to resolve aliases recursively
+when they are made public through the [`__all__`][__all__] variable.
+By default, the handler will only resolve aliases when they point at a private sibling
+of the source package, for example aliases going from `ast` to `_ast`.
+Set `load_external_modules` to `False` to prevent even that.
+
+WARNING: **Use with caution**
+This can load a *lot* of modules through [Griffe],
+slowing down your build or triggering errors that Griffe does not yet handle.
+**We recommend using the [`preload_modules`][] option instead**,
+which acts as an include-list rather than as include-all.
+
+Example:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ load_external_modules: true
+```
+
+ [__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package
+
+[](){#setting-locale}
+#### ~~`locale`~~
+
+**Deprecated.** Use mkdocstrings' own `locale` setting.
+
+~~The locale to use when translating template strings.~~
+
+[](){#setting-paths}
+#### `paths`
+
+This option is used to provide filesystem paths in which to search for Python modules.
+Non-absolute paths are computed as relative to MkDocs configuration file. Example:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ paths: [src] # search packages in the src folder
+```
+
+More details at [Finding modules](#finding-modules).
+
+[](){#setting-options}
+### Global/local options
+
+The other options can be used both globally *and* locally, under the `options` key.
+For example, globally:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ do_something: true
+```
+
+...and locally, overriding the global configuration:
+
+```md title="docs/some_page.md"
+::: package.module.class
+ options:
+ do_something: false
+```
+
+These options affect how the documentation is collected from sources and rendered.
+See the following tables summarizing the options, and get more details for each option
+in the following pages:
+
+- [General options](configuration/general.md): various options that do not fit in the other categories
+- [Headings options](configuration/headings.md): options related to headings and the table of contents
+ (or sidebar, depending on the theme used)
+- [Members options](configuration/members.md): options related to filtering or ordering members
+ in the generated documentation
+- [Docstrings options](configuration/docstrings.md): options related to docstrings (parsing and rendering)
+- [Signature options](configuration/signatures.md): options related to signatures and type annotations
+
+## Finding modules
+
+There are multiple ways to tell the handler where to find your packages/modules.
+
+**The recommended method is to use the `paths` option, as it's the only one
+that works with the `-f` option of MkDocs, allowing to build the documentation
+from any location on the file system.** Indeed, the paths provided with the
+`paths` option are computed as relative to the configuration file (mkdocs.yml),
+so that the current working directory has no impact on the build process:
+*you can build the docs from any location on your filesystem*.
+
+### Using the `paths` option
+
+TIP: **This is the recommended method.**
+
+1. mkdocs.yml in root, package in root
+ ```tree
+ root/
+ mkdocs.yml
+ package/
+ ```
+
+ ```yaml title="mkdocs.yml"
+ plugins:
+ - mkdocstrings:
+ handlers:
+ python:
+ paths: [.] # actually not needed, default
+ ```
+
+1. mkdocs.yml in root, package in subfolder
+ ```tree
+ root/
+ mkdocs.yml
+ src/
+ package/
+ ```
+
+ ```yaml title="mkdocs.yml"
+ plugins:
+ - mkdocstrings:
+ handlers:
+ python:
+ paths: [src]
+ ```
+
+1. mkdocs.yml in subfolder, package in root
+ ```tree
+ root/
+ docs/
+ mkdocs.yml
+ package/
+ ```
+
+ ```yaml title="mkdocs.yml"
+ plugins:
+ - mkdocstrings:
+ handlers:
+ python:
+ paths: [..]
+ ```
+
+1. mkdocs.yml in subfolder, package in subfolder
+ ```tree
+ root/
+ docs/
+ mkdocs.yml
+ src/
+ package/
+ ```
+
+ ```yaml title="mkdocs.yml"
+ plugins:
+ - mkdocstrings:
+ handlers:
+ python:
+ paths: [../src]
+ ```
+
+Except for case 1, which is supported by default, **we strongly recommend
+setting the path to your packages using this option, even if it works without it**
+(for example because your project manager automatically adds `src` to PYTHONPATH),
+to make sure anyone can build your docs from any location on their filesystem.
+
+### Using the PYTHONPATH environment variable
+
+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.
+
+You can take advantage of the usual Python loading mechanisms.
+In Bash and other shells, you can run your command like this
+(note the prepended `PYTHONPATH=...`):
+
+1. mkdocs.yml in root, package in root
+ ```tree
+ root/
+ mkdocs.yml
+ package/
+ ```
+
+ ```bash
+ PYTHONPATH=. mkdocs build # actually not needed, default
+ ```
+
+1. mkdocs.yml in root, package in subfolder
+ ```tree
+ root/
+ mkdocs.yml
+ src/
+ package/
+ ```
+
+ ```bash
+ PYTHONPATH=src mkdocs build
+ ```
+
+1. mkdocs.yml in subfolder, package in root
+ ```tree
+ root/
+ docs/
+ mkdocs.yml
+ package/
+ ```
+
+ ```bash
+ PYTHONPATH=. mkdocs build -f docs/mkdocs.yml
+ ```
+
+1. mkdocs.yml in subfolder, package in subfolder
+ ```tree
+ root/
+ docs/
+ mkdocs.yml
+ src/
+ package/
+ ```
+
+ ```bash
+ PYTHONPATH=src mkdocs build -f docs/mkdocs.yml
+ ```
+
+### Installing your package in the current Python environment
+
+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.
+
+Install your package in the current environment, and run MkDocs:
+
+/// tab | pip
+```bash
+. venv/bin/activate
+pip install -e .
+mkdocs build
+```
+///
+
+/// tab | PDM
+```bash
+pdm install
+pdm run mkdocs build
+```
+///
+
+/// tab | Poetry
+```bash
+poetry install
+poetry run mkdocs build
+```
+///
+
+## Recommended settings
+
+If you're in a hurry, here is the configuration we recommend for the Python handler.
+
+```yaml
+- mkdocstrings:
+ handlers:
+ python:
+
+ # Where to find your sources, see "Finding modules".
+ paths: [src]
+
+ # Load object inventories to enable cross-references to other projects.
+ inventories:
+ - https://docs.python.org/3/objects.inv
+ # Also load inventories of your dependencies, generally served at
+ # https://docs-url-for-your-dependency/objects.inv.
+
+ options:
+
+ # DOCSTRINGS -------------------------------------------------------------
+ docstring_options:
+ # Discard first line of `__init__` method docstrings,
+ # useful when merging such docstrings into their parent class'.
+ ignore_init_summary: true
+
+ # Tables are generally too large, lists will fix this.
+ docstring_section_style: list
+
+ # CROSS-REFERENCES -------------------------------------------------------
+ # Enable relative crossrefs and scoped crossrefs, see Docstrings options.
+ relative_crossrefs: true # Sponsors only!
+ scoped_crossrefs: true # Sponsors only!
+
+ # Enable cross-references in signatures.
+ signature_crossrefs: true
+
+ # Unwrap actual types from `Annotated` type annotations.
+ unwrap_annotated: true
+
+ # MEMBERS ----------------------------------------------------------------
+ # Only render pulic symbols.
+ filters: public # Sponsors only!
+ # Comment the option otherwise to get the default filters.
+
+ # Show class inherited members.
+ inherited_members: true
+
+ # Render auto-generated summaries of attributes, functions, etc.
+ # at the start of each symbol's documentation.
+ summary: true
+
+ # HEADINGS ---------------------------------------------------------------
+ # For auto-generated pages, one module per page,
+ # make the module heading be the H1 heading of the page.
+ heading_level: 1
+
+ # Render headings for parameters, making them linkable.
+ parameter_headings: true
+
+ # Render headings for type parameters too.
+ type_parameter_headings: true
+
+ # Always show the heading for the symbol you render with `::: id`.
+ show_root_heading: true
+
+ # Only show the name of the symbols you inject render `::: id`.
+ show_root_full_path: false
+
+ # Show the type of symbol (class, function, etc.) in the heading.
+ show_symbol_type_heading: true
+
+ # Show the type of symbol (class, function, etc.) in the table of contents.
+ show_symbol_type_toc: true
+
+ # SIGNATURES -------------------------------------------------------------
+ # Format code to 80 + 10% margin (Black and Ruff defaults)
+ # in signatures and attribute value code blocks.
+ # Needs Black/Ruff installed.
+ line_length: 88
+
+ # Merge signature and docstring of `__init__` methods
+ # into their parent class signature and docstring.
+ merge_init_into_class: true
+
+ # Render signatures and attribute values in a separate code block,
+ # below the symbol heading.
+ separate_signature: true
+
+ # Show type annotations in signatures.
+ show_signature_annotations: true
+
+ # Show type parameters in signatures.
+ show_signature_type_parameters: true
+
+ # OTHER ------------------------------------------------------------------
+ # Show backlinks to other documentation sections within each symbol.
+ backlinks: tree # Sponsors only!
+
+ # Show base classes OR inheritance diagram.
+ show_bases: false
+ show_inheritance_diagram: true # Sponsors only!
+```
diff --git a/duties.py b/duties.py
index 3ad804dd..3aa9b662 100644
--- a/duties.py
+++ b/duties.py
@@ -1,357 +1,200 @@
"""Development tasks."""
-import importlib
+from __future__ import annotations
+
import os
import re
import sys
-import tempfile
-from contextlib import suppress
-from io import StringIO
from pathlib import Path
-from typing import List, Optional, Pattern
-from urllib.request import urlopen
+from typing import TYPE_CHECKING
+
+from duty import duty, tools
+
+if TYPE_CHECKING:
+ from duty.context import Context
-from duty import duty
-PY_SRC_PATHS = (Path(_) for _ in ("src", "tests", "duties.py", "docs"))
+PY_SRC_PATHS = (Path(_) for _ in ("src", "tests", "duties.py", "scripts"))
PY_SRC_LIST = tuple(str(_) for _ in PY_SRC_PATHS)
PY_SRC = " ".join(PY_SRC_LIST)
-TESTING = os.environ.get("TESTING", "0") in {"1", "true"}
CI = os.environ.get("CI", "0") in {"1", "true", "yes", ""}
WINDOWS = os.name == "nt"
PTY = not WINDOWS and not CI
+MULTIRUN = os.environ.get("MULTIRUN", "0") == "1"
+PY_VERSION = f"{sys.version_info.major}{sys.version_info.minor}"
+PY_DEV = "314"
-def _latest(lines: List[str], regex: Pattern) -> Optional[str]:
- for line in lines:
- match = regex.search(line)
- if match:
- return match.groupdict()["version"]
- return None
+def pyprefix(title: str) -> str:
+ if MULTIRUN:
+ prefix = f"(python{sys.version_info.major}.{sys.version_info.minor})"
+ return f"{prefix:14}{title}"
+ return title
-def _unreleased(versions, last_release):
- for index, version in enumerate(versions):
- if version.tag == last_release:
- return versions[:index]
- return versions
+def _get_changelog_version() -> str:
+ changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$")
+ with Path(__file__).parent.joinpath("CHANGELOG.md").open("r", encoding="utf8") as file:
+ return next(filter(bool, map(changelog_version_re.match, file))).group(1) # type: ignore[union-attr]
-def update_changelog(
- inplace_file: str,
- marker: str,
- version_regex: str,
- template_url: str,
-) -> None:
- """
- Update the given changelog file in place.
+@duty
+def changelog(ctx: Context, bump: str = "") -> None:
+ """Update the changelog in-place with latest commits.
- Arguments:
- inplace_file: The file to update in-place.
- marker: The line after which to insert new contents.
- version_regex: A regular expression to find currently documented versions in the file.
- template_url: The URL to the Jinja template used to render contents.
+ Parameters:
+ bump: Bump option passed to git-changelog.
"""
- from git_changelog.build import Changelog
- from git_changelog.commit import AngularStyle
- from jinja2.sandbox import SandboxedEnvironment
-
- AngularStyle.DEFAULT_RENDER.insert(0, AngularStyle.TYPES["build"])
- env = SandboxedEnvironment(autoescape=False)
- template_text = urlopen(template_url).read().decode("utf8") # noqa: S310
- template = env.from_string(template_text)
- changelog = Changelog(".", style="angular")
+ ctx.run(tools.git_changelog(bump=bump or None), title="Updating changelog")
+ ctx.run(tools.yore.check(bump=bump or _get_changelog_version()), title="Checking legacy code")
- if len(changelog.versions_list) == 1:
- last_version = changelog.versions_list[0]
- if last_version.planned_tag is None:
- planned_tag = "0.1.0"
- last_version.tag = planned_tag
- last_version.url += planned_tag
- last_version.compare_url = last_version.compare_url.replace("HEAD", planned_tag)
- with open(inplace_file, "r") as changelog_file:
- lines = changelog_file.read().splitlines()
+@duty(pre=["check-quality", "check-types", "check-docs", "check-api"])
+def check(ctx: Context) -> None:
+ """Check it all!"""
- last_released = _latest(lines, re.compile(version_regex))
- if last_released:
- changelog.versions_list = _unreleased(changelog.versions_list, last_released)
- rendered = template.render(changelog=changelog, inplace=True)
- lines[lines.index(marker)] = rendered
-
- with open(inplace_file, "w") as changelog_file: # noqa: WPS440
- changelog_file.write("\n".join(lines).rstrip("\n") + "\n")
-
-
-@duty
-def changelog(ctx):
- """
- Update the changelog in-place with latest commits.
- Arguments:
- ctx: The context instance (passed automatically).
- """
- commit = "166758a98d5e544aaa94fda698128e00733497f4"
- template_url = f"https://raw.githubusercontent.com/pawamoy/jinja-templates/{commit}/keepachangelog.md"
+@duty(nofail=PY_VERSION == PY_DEV)
+def check_quality(ctx: Context) -> None:
+ """Check the code quality."""
ctx.run(
- update_changelog,
- kwargs={
- "inplace_file": "CHANGELOG.md",
- "marker": "",
- "version_regex": r"^## \[v?(?P-
+
- Parameter:
- Type Parameter:
- Attribute:
- Function:
- Method:
- Class:
- Type Alias:
- Module:
{text}"
- return Markup(text).format(**variables)
-
-
-def _keep_object(name, filters):
- keep = None
- rules = set()
- for regex, exclude in filters:
- rules.add(exclude)
- if regex.search(name):
- keep = not exclude
- if keep is None:
- if rules == {False}: # noqa: WPS531
- # only included stuff, no match = reject
- return False
- # only excluded stuff, or included and excluded stuff, no match = keep
- return True
- return keep
-
-
-def do_filter_objects(
- objects_dictionary: dict[str, Object | Alias],
- filters: list[tuple[bool, Pattern]] | None = None,
- members_list: list[str] | None = None,
- keep_no_docstrings: bool = True,
-) -> list[Object | Alias]:
- """Filter a dictionary of objects based on their docstrings.
-
- Parameters:
- objects_dictionary: The dictionary of objects.
- filters: Filters to apply, based on members' names.
- Each element is a tuple: a pattern, and a boolean indicating whether
- to reject the object if the pattern matches.
- members_list: An optional, explicit list of members to keep.
- When given and empty, return an empty list.
- When given and not empty, ignore filters and docstrings presence/absence.
- keep_no_docstrings: Whether to keep objects with no/empty docstrings (recursive check).
-
- Returns:
- A list of objects.
- """
- if members_list is not None:
- if not members_list:
- return []
- return [obj for obj in objects_dictionary.values() if obj.name in set(members_list)]
- objects = list(objects_dictionary.values())
- if filters:
- objects = [obj for obj in objects if _keep_object(obj.name, filters)]
- if keep_no_docstrings:
- return objects
- return [obj for obj in objects if obj.has_docstrings]
-
-
-@lru_cache(maxsize=1)
-def _get_black_formatter():
- try:
- from black import Mode, format_str
- except ModuleNotFoundError:
- logger.warning("Formatting signatures requires Black to be installed.")
- return lambda text, _: text
-
- def formatter(code, line_length): # noqa: WPS430
- mode = Mode(line_length=line_length)
- return format_str(code, mode=mode)
-
- return formatter
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html
deleted file mode 100644
index 019e7fae..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html
+++ /dev/null
@@ -1,69 +0,0 @@
-{{ log.debug("Rendering " + attribute.path) }}
-
-
-{% with html_id = attribute.path %}
-
- {% if root %}
- {% set show_full_path = config.show_root_full_path %}
- {% set root_members = True %}
- {% elif root_members %}
- {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
- {% set root_members = False %}
- {% else %}
- {% set show_full_path = config.show_object_full_path %}
- {% endif %}
-
- {% if not root or config.show_root_heading %}
-
- {% filter heading(heading_level,
- role="data" if attribute.parent.kind.value == "module" else "attr",
- id=html_id,
- class="doc doc-heading",
- toc_label=attribute.name) %}
-
- {% if config.separate_signature %}
- {% if show_full_path %}{{ attribute.path }}{% else %}{{ attribute.name }}{% endif %}
- {% else %}
- {% filter highlight(language="python", inline=True) %}
- {% if show_full_path %}{{ attribute.path }}{% else %}{{ attribute.name }}{% endif %}
- {% if attribute.annotation %}: {{ attribute.annotation }}{% endif %}
- {% if attribute.value %} = {{ attribute.value }}{% endif %}
- {% endfilter %}
- {% endif %}
-
- {% with labels = attribute.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
-
- {% endfilter %}
-
- {% if config.separate_signature %}
- {% filter highlight(language="python", inline=False) %}
- {% filter format_code(config.line_length) %}
- {% if show_full_path %}{{ attribute.path }}{% else %}{{ attribute.name }}{% endif %}
- {% if attribute.annotation %}: {{ attribute.annotation|safe }}{% endif %}
- {% if attribute.value %} = {{ attribute.value|safe }}{% endif %}
- {% endfilter %}
- {% endfilter %}
- {% endif %}
-
- {% else %}
- {% if config.show_root_toc_entry %}
- {% filter heading(heading_level,
- role="data" if attribute.parent.kind.value == "module" else "attr",
- id=html_id,
- toc_label=attribute.path if config.show_root_full_path else attribute.name,
- hidden=True) %}
- {% endfilter %}
- {% endif %}
- {% set heading_level = heading_level - 1 %}
- {% endif %}
-
-
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
new file mode 100644
index 00000000..65054689
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
@@ -0,0 +1,128 @@
+{#- Template for Python attributes.
+
+This template renders a Python attribute (or variable).
+This can be a module attribute or a class attribute.
+
+Context:
+ attribute (griffe.Attribute): The attribute to render.
+ root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+ heading_level (int): The HTML heading level to use.
+ config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering " + attribute.path) }}
+{% endblock logs %}
+
+
- {% with docstring_sections = attribute.docstring.parsed %}
- {% include "docstring.html" with context %}
- {% endwith %}
-
-
-{% endwith %}
-
+ {% with obj = attribute, html_id = attribute.path %}
+
+ {% if root %}
+ {% set show_full_path = config.show_root_full_path %}
+ {% set root_members = True %}
+ {% elif root_members %}
+ {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+ {% set root_members = False %}
+ {% else %}
+ {% set show_full_path = config.show_object_full_path %}
+ {% endif %}
+
+ {% set attribute_name = attribute.path if show_full_path else attribute.name %}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="data" if attribute.parent.kind.value == "module" else "attr",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=('
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/backlinks.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/backlinks.html.jinja
new file mode 100644
index 00000000..930da3e8
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/backlinks.html.jinja
@@ -0,0 +1,66 @@
+{#- Template for backlinks.
+
+This template renders backlinks.
+
+Context:
+ backlinks (Mapping[str, Iterable[str]]): The backlinks to render.
+ config (dict): The configuration options.
+ verbose_type (Mapping[str, str]): The verbose backlink types.
+ default_crumb (BacklinkCrumb): A default, empty crumb.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro render_crumb(crumb, last=false) %}
+
+ {% if crumb.url and crumb.title %}
+ {{ crumb.title | safe }}
+ {% elif crumb.title %}
+ {{ crumb.title | safe }}
+ {% endif %}
+
+{% endmacro %}
+
+{% macro render_tree(tree) %}
+
+ {% 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 %}
+ {% include "docstring.html.jinja" with context %}
+ {% endwith %}
+ {% endblock docstring %}
+
+ {% if config.backlinks %}
+
+
+ {% endwith %}
+-
+ {% for node, child in tree | dictsort %}
+
- + {% for crumb in node %} + {{ render_crumb(crumb, last=loop.last and not child) }} + {% endfor %} + {% if child %} + {{ render_tree(child) }} + {% endif %} + + {% endfor %} +
+ {% if config.backlinks == "tree" %}
+ {% for backlink_type, backlink_list in backlinks | dictsort %}
+ {{ verbose_type[backlink_type] }}:
+ {{ render_tree(backlink_list|backlink_tree) }}
+ {% endfor %}
+ {% elif config.backlinks == "flat" %}
+ {% for backlink_type, backlink_list in backlinks | dictsort %}
+ {{ verbose_type[backlink_type] }}:
+
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html b/src/mkdocstrings_handlers/python/templates/material/_base/children.html
deleted file mode 100644
index 71755ea7..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html
+++ /dev/null
@@ -1,126 +0,0 @@
-{% if obj.members %}
- {{ log.debug("Rendering children of " + obj.path) }}
-
- -
+ {% for backlink in backlink_list | sort(attribute="crumbs") %}
+
- + {% for crumb in backlink.crumbs %} + {{ render_crumb(crumb, last=loop.last) }} + {% endfor %} + + {% endfor %} +
-
- {% if root_members %}
- {% set members_list = config.members %}
- {% else %}
- {% set members_list = none %}
- {% endif %}
-
- {% if config.group_by_category %}
-
- {% with %}
-
- {% if config.show_category_heading %}
- {% set extra_level = 1 %}
- {% else %}
- {% set extra_level = 0 %}
- {% endif %}
-
- {% with attributes = obj.attributes|filter_objects(config.filters, members_list, config.show_if_no_docstring) %}
- {% if attributes %}
- {% if config.show_category_heading %}
- {% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %}
- {% endif %}
- {% with heading_level = heading_level + extra_level %}
- {% for attribute in attributes|order_members(config.members_order, members_list) %}
- {% if not attribute.is_alias or attribute.is_explicitely_exported %}
- {% include "attribute.html" with context %}
- {% endif %}
- {% endfor %}
- {% endwith %}
- {% endif %}
- {% endwith %}
-
- {% with classes = obj.classes|filter_objects(config.filters, members_list, config.show_if_no_docstring) %}
- {% if classes %}
- {% if config.show_category_heading %}
- {% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %}
- {% endif %}
- {% with heading_level = heading_level + extra_level %}
- {% for class in classes|order_members(config.members_order, members_list) %}
- {% if not class.is_alias or class.is_explicitely_exported %}
- {% include "class.html" with context %}
- {% endif %}
- {% endfor %}
- {% endwith %}
- {% endif %}
- {% endwith %}
-
- {% with functions = obj.functions|filter_objects(config.filters, members_list, config.show_if_no_docstring) %}
- {% if functions %}
- {% if config.show_category_heading %}
- {% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %}
- {% endif %}
- {% with heading_level = heading_level + extra_level %}
- {% for function in functions|order_members(config.members_order, members_list) %}
- {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
- {% if not function.is_alias or function.is_explicitely_exported %}
- {% include "function.html" with context %}
- {% endif %}
- {% endif %}
- {% endfor %}
- {% endwith %}
- {% endif %}
- {% endwith %}
-
- {% if config.show_submodules %}
- {% with modules = obj.modules|filter_objects(config.filters, members_list, config.show_if_no_docstring) %}
- {% if modules %}
- {% if config.show_category_heading %}
- {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %}
- {% endif %}
- {% with heading_level = heading_level + extra_level %}
- {% for module in modules|order_members(config.members_order, members_list) %}
- {% if not module.is_alias or module.is_explicitely_exported %}
- {% include "module.html" with context %}
- {% endif %}
- {% endfor %}
- {% endwith %}
- {% endif %}
- {% endwith %}
- {% endif %}
-
- {% endwith %}
-
- {% else %}
-
- {% for child in obj.members|
- filter_objects(config.filters, members_list, config.show_if_no_docstring)|
- order_members(config.members_order, members_list) %}
-
- {% if not (obj.kind.value == "class" and child.name == "__init__" and config.merge_init_into_class) %}
-
- {% if child.kind.value == "attribute" %}
- {% with attribute = child %}
- {% include "attribute.html" with context %}
- {% endwith %}
-
- {% elif child.kind.value == "class" %}
- {% with class = child %}
- {% include "class.html" with context %}
- {% endwith %}
-
- {% elif child.kind.value == "function" %}
- {% with function = child %}
- {% include "function.html" with context %}
- {% endwith %}
-
- {% elif child.kind.value == "module" and config.show_submodules %}
- {% with module = child %}
- {% include "module.html" with context %}
- {% endwith %}
-
- {% endif %}
-
- {% endif %}
-
- {% endfor %}
-
- {% endif %}
-
-
-
-{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
new file mode 100644
index 00000000..63f3b1a6
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
@@ -0,0 +1,200 @@
+{#- Template for members (children) of an object.
+
+This template iterates on members of a given object and renders them.
+It can group members by category (attributes, classes, functions, modules) or render them in a flat list.
+
+Context:
+ obj (griffe.Object): The object to render.
+ config (dict): The configuration options.
+ root_members (bool): Whether the object is the root object.
+ heading_level (int): The HTML heading level to use.
+-#}
+
+{% 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) }}
+ {% endblock logs %}
+
+ {% import "language.html.jinja" as lang with context %}
+ {#- Language module providing the `t` translation method. -#}
+
+
+
+ {% if root_members %}
+ {% set members_list = config.members %}
+ {% else %}
+ {% set members_list = none %}
+ {% endif %}
+
+ {% if config.group_by_category %}
+
+ {% with %}
+
+ {% if config.show_category_heading %}
+ {% set extra_level = 1 %}
+ {% else %}
+ {% set extra_level = 0 %}
+ {% endif %}
+
+ {% with attributes = obj.attributes|filter_objects(
+ filters=config.filters,
+ members_list=members_list,
+ inherited_members=config.inherited_members,
+ keep_no_docstrings=config.show_if_no_docstring,
+ ) %}
+ {% if attributes %}
+ {% if config.show_category_heading %}
+ {% filter heading(heading_level, id=html_id ~ "-attributes", skip_inventory=config.skip_local_inventory) %}{{ lang.t("Attributes") }}{% endfilter %}
+ {% endif %}
+ {% with heading_level = heading_level + extra_level %}
+ {% for attribute in attributes|order_members(config.members_order, members_list) %}
+ {% if config.filters == "public" or members_list is not none or (not attribute.is_imported or attribute.is_public) %}
+ {% include attribute|get_template with context %}
+ {% endif %}
+ {% endfor %}
+ {% endwith %}
+ {% endif %}
+ {% endwith %}
+
+ {% with type_aliases = obj.type_aliases|filter_objects(
+ filters=config.filters,
+ members_list=members_list,
+ inherited_members=config.inherited_members,
+ keep_no_docstrings=config.show_if_no_docstring,
+ ) %}
+ {% if type_aliases %}
+ {% if config.show_category_heading %}
+ {% filter heading(heading_level, id=html_id ~ "-type_aliases") %}{{ lang.t("Type Aliases") }}{% endfilter %}
+ {% endif %}
+ {% with heading_level = heading_level + extra_level %}
+ {% for type_alias in type_aliases|order_members(config.members_order, members_list) %}
+ {% if config.filters == "public" or members_list is not none or (not type_alias.is_imported or type_alias.is_public) %}
+ {% include type_alias|get_template with context %}
+ {% endif %}
+ {% endfor %}
+ {% endwith %}
+ {% endif %}
+ {% endwith %}
+
+ {% with classes = obj.classes|filter_objects(
+ filters=config.filters,
+ members_list=members_list,
+ inherited_members=config.inherited_members,
+ keep_no_docstrings=config.show_if_no_docstring,
+ ) %}
+ {% if classes %}
+ {% if config.show_category_heading %}
+ {% filter heading(heading_level, id=html_id ~ "-classes", skip_inventory=config.skip_local_inventory) %}{{ lang.t("Classes") }}{% endfilter %}
+ {% endif %}
+ {% with heading_level = heading_level + extra_level %}
+ {% for class in classes|order_members(config.members_order, members_list) %}
+ {% if config.filters == "public" or members_list is not none or (not class.is_imported or class.is_public) %}
+ {% include class|get_template with context %}
+ {% endif %}
+ {% endfor %}
+ {% endwith %}
+ {% endif %}
+ {% endwith %}
+
+ {% with functions = obj.functions|filter_objects(
+ filters=config.filters,
+ members_list=members_list,
+ inherited_members=config.inherited_members,
+ keep_no_docstrings=config.show_if_no_docstring,
+ ) %}
+ {% if functions %}
+ {% if config.show_category_heading %}
+ {% filter heading(heading_level, id=html_id ~ "-functions", skip_inventory=config.skip_local_inventory) %}{{ lang.t("Functions") }}{% endfilter %}
+ {% endif %}
+ {% with heading_level = heading_level + extra_level %}
+ {% for function in functions|order_members(config.members_order, members_list) %}
+ {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
+ {% if config.filters == "public" or members_list is not none or (not function.is_imported or function.is_public) %}
+ {% include function|get_template with context %}
+ {% endif %}
+ {% endif %}
+ {% endfor %}
+ {% endwith %}
+ {% endif %}
+ {% endwith %}
+
+ {% if config.show_submodules %}
+ {% with modules = obj.modules|filter_objects(
+ filters=config.filters,
+ members_list=members_list,
+ inherited_members=config.inherited_members,
+ keep_no_docstrings=config.show_if_no_docstring,
+ ) %}
+ {% if modules %}
+ {% if config.show_category_heading %}
+ {% filter heading(heading_level, id=html_id ~ "-modules", skip_inventory=config.skip_local_inventory) %}{{ lang.t("Modules") }}{% endfilter %}
+ {% endif %}
+ {% with heading_level = heading_level + extra_level %}
+ {% for module in modules|order_members("alphabetical", members_list) %}
+ {% if config.filters == "public" or members_list is not none or (not module.is_alias or module.is_public) %}
+ {% include module|get_template with context %}
+ {% endif %}
+ {% endfor %}
+ {% endwith %}
+ {% endif %}
+ {% endwith %}
+ {% endif %}
+
+ {% endwith %}
+
+ {% else %}
+
+ {% for child in obj.all_members
+ |filter_objects(
+ filters=config.filters,
+ members_list=members_list,
+ inherited_members=config.inherited_members,
+ keep_no_docstrings=config.show_if_no_docstring,
+ )
+ |order_members(config.members_order, members_list)
+ %}
+
+ {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %}
+
+ {% if config.filters == "public" or members_list is not none or (not child.is_imported or child.is_public) %}
+ {% if child.is_attribute %}
+ {% with attribute = child %}
+ {% include attribute|get_template with context %}
+ {% endwith %}
+
+ {% elif child.is_type_alias %}
+ {% with type_alias = child %}
+ {% include type_alias|get_template with context %}
+ {% endwith %}
+
+ {% elif child.is_class %}
+ {% with class = child %}
+ {% include class|get_template with context %}
+ {% endwith %}
+
+ {% elif child.is_function %}
+ {% with function = child %}
+ {% include function|get_template with context %}
+ {% endwith %}
+
+ {% elif child.is_module and config.show_submodules %}
+ {% with module = child %}
+ {% include module|get_template with context %}
+ {% endwith %}
+
+ {% endif %}
+ {% endif %}
+
+ {% endif %}
+
+ {% endfor %}
+
+ {% endif %}
+
+
+
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html b/src/mkdocstrings_handlers/python/templates/material/_base/class.html
deleted file mode 100644
index ff102c88..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html
+++ /dev/null
@@ -1,113 +0,0 @@
-{{ log.debug("Rendering " + class.path) }}
-
-
-{% with html_id = class.path %}
-
- {% if root %}
- {% set show_full_path = config.show_root_full_path %}
- {% set root_members = True %}
- {% elif root_members %}
- {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
- {% set root_members = False %}
- {% else %}
- {% set show_full_path = config.show_object_full_path %}
- {% endif %}
-
- {% if not root or config.show_root_heading %}
-
- {% filter heading(heading_level,
- role="class",
- id=html_id,
- class="doc doc-heading",
- toc_label=class.name) %}
-
- {% if config.separate_signature %}
- {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
- {% elif config.merge_init_into_class and "__init__" in class.members -%}
- {%- with function = class.members["__init__"] -%}
- {%- filter highlight(language="python", inline=True) -%}
- {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
- {%- include "signature.html" with context -%}
- {%- endfilter -%}
- {%- endwith -%}
- {% else %}
-
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
new file mode 100644
index 00000000..57f9fd5a
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
@@ -0,0 +1,291 @@
+{#- Template for Python classes.
+
+This template renders a Python class.
+
+Context:
+ class (griffe.Class): The class to render.
+ root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+ heading_level (int): The HTML heading level to use.
+ config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering " + class.path) }}
+{% endblock logs %}
+
+{% import "language.html.jinja" as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
- {% endif %}
-
- {% with labels = class.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
-
- {% endfilter %}
-
- {% if config.separate_signature and config.merge_init_into_class %}
- {% if "__init__" in class.members %}
- {% with function = class.members["__init__"] %}
- {% filter highlight(language="python", inline=False) %}
- {% filter format_signature(config.line_length) %}
- {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
- {% include "signature.html" with context %}
- {% endfilter %}
- {% endfilter %}
- {% endwith %}
- {% endif %}
- {% endif %}
-
- {% else %}
- {% if config.show_root_toc_entry %}
- {% filter heading(heading_level,
- role="class",
- id=html_id,
- toc_label=class.path if config.show_root_full_path else class.name,
- hidden=True) %}
- {% endfilter %}
- {% endif %}
- {% set heading_level = heading_level - 1 %}
- {% endif %}
-
-
- {% if config.show_bases and class.bases %}
-
-
-{% endwith %}
-
- Bases: {% for expression in class.bases -%}
- {% include "expression.html" with context %}{% if not loop.last %}, {% endif %}
- {% endfor -%}
-
- Source code in
- {{ class.members["__init__"].source|highlight(language="python", linestart=class.members["__init__"].lineno, linenums=True) }}
-
- {% endif %}
- {% elif class.source %}
- Source code in {{ class.relative_filepath }}
- {{ class.members["__init__"].source|highlight(language="python", linestart=class.members["__init__"].lineno, linenums=True) }}
-
- Source code in
- {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
-
- {% endif %}
- {% endif %}
-
- {% with obj = class %}
- {% set root = False %}
- {% set heading_level = heading_level + 1 %}
- {% include "children.html" with context %}
- {% endwith %}
- Source code in {{ class.relative_filepath }}
- {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
-
+ {% with obj = class, html_id = class.path, all_members = class.all_members %}
+
+ {% if root %}
+ {% set show_full_path = config.show_root_full_path %}
+ {% set root_members = True %}
+ {% elif root_members %}
+ {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+ {% set root_members = False %}
+ {% else %}
+ {% set show_full_path = config.show_object_full_path %}
+ {% endif %}
+
+ {% set class_name = class.path if show_full_path else class.name %}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="class",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=('
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html
deleted file mode 100644
index bd1b6963..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html
+++ /dev/null
@@ -1,28 +0,0 @@
-{% if docstring_sections %}
- {{ log.debug("Rendering docstring") }}
- {% for section in docstring_sections %}
- {% if section.kind.value == "text" %}
- {{ section.value|convert_markdown(heading_level, html_id) }}
- {% elif section.kind.value == "attributes" %}
- {% include "docstring/attributes.html" with context %}
- {% elif section.kind.value == "parameters" %}
- {% include "docstring/parameters.html" with context %}
- {% elif section.kind.value == "other parameters" %}
- {% include "docstring/other_parameters.html" with context %}
- {% elif section.kind.value == "raises" %}
- {% include "docstring/raises.html" with context %}
- {% elif section.kind.value == "warns" %}
- {% include "docstring/warns.html" with context %}
- {% elif section.kind.value == "yields" %}
- {% include "docstring/yields.html" with context %}
- {% elif section.kind.value == "receives" %}
- {% include "docstring/receives.html" with context %}
- {% elif section.kind.value == "returns" %}
- {% include "docstring/returns.html" with context %}
- {% elif section.kind.value == "examples" %}
- {% include "docstring/examples.html" with context %}
- {% elif section.kind.value == "admonition" %}
- {% include "docstring/admonition.html" with context %}
- {% endif %}
- {% endfor %}
-{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja
new file mode 100644
index 00000000..a00a0249
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja
@@ -0,0 +1,59 @@
+{#- Template for docstrings.
+
+This template renders Python docstrings.
+Griffe parses docstrings into a list of sections, each with a `kind` and a `value`.
+This template can then iterate on these sections and render them according to the configuration.
+
+Context:
+ docstring_sections (list[griffe.DocstringSection]): The list of docstring sections.
+ config (dict): The configuration dictionary.
+ heading_level (int): The heading level to use for Markdown conversion.
+ html_id (str): The HTML ID to use for Markdown conversion.
+-#}
+
+{% 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") }}
+ {% endblock logs %}
+ {% with autoref_hook = AutorefsHook(obj, config) %}
+ {% for section in docstring_sections %}
+ {% if config.show_docstring_description and section.kind.value == "text" %}
+ {{ section.value|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+ {% elif config.show_docstring_attributes and section.kind.value == "attributes" %}
+ {% include "docstring/attributes.html.jinja" with context %}
+ {% elif config.show_docstring_functions and section.kind.value == "functions" %}
+ {% include "docstring/functions.html.jinja" with context %}
+ {% elif config.show_docstring_classes and section.kind.value == "classes" %}
+ {% include "docstring/classes.html.jinja" with context %}
+ {% elif config.show_docstring_type_aliases and section.kind.value == "type aliases" %}
+ {% include "docstring/type_aliases.html.jinja" with context %}
+ {% elif config.show_docstring_modules and section.kind.value == "modules" %}
+ {% include "docstring/modules.html.jinja" with context %}
+ {% elif config.show_docstring_type_parameters and section.kind.value == "type parameters" %}
+ {% include "docstring/type_parameters.html.jinja" with context %}
+ {% elif config.show_docstring_parameters and section.kind.value == "parameters" %}
+ {% include "docstring/parameters.html.jinja" with context %}
+ {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %}
+ {% include "docstring/other_parameters.html.jinja" with context %}
+ {% elif config.show_docstring_raises and section.kind.value == "raises" %}
+ {% include "docstring/raises.html.jinja" with context %}
+ {% elif config.show_docstring_warns and section.kind.value == "warns" %}
+ {% include "docstring/warns.html.jinja" with context %}
+ {% elif config.show_docstring_yields and section.kind.value == "yields" %}
+ {% include "docstring/yields.html.jinja" with context %}
+ {% elif config.show_docstring_receives and section.kind.value == "receives" %}
+ {% include "docstring/receives.html.jinja" with context %}
+ {% elif config.show_docstring_returns and section.kind.value == "returns" %}
+ {% include "docstring/returns.html.jinja" with context %}
+ {% elif config.show_docstring_examples and section.kind.value == "examples" %}
+ {% include "docstring/examples.html.jinja" with context %}
+ {% elif config.show_docstring_description and section.kind.value == "admonition" %}
+ {% include "docstring/admonition.html.jinja" with context %}
+ {% endif %}
+ {% endfor %}
+ {% endwith %}
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html
deleted file mode 100644
index b3cab485..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html
+++ /dev/null
@@ -1,5 +0,0 @@
-{{ log.debug("Rendering admonition") }}
-{{ class_name }}
+ {% endif %}
+ {% endblock heading %}
+
+ {% block labels scoped %}
+ {#- Labels block.
+
+ This block renders the labels for the class.
+ -#}
+ {% with labels = class.labels %}
+ {% include "labels.html.jinja" with context %}
+ {% endwith %}
+ {% endblock labels %}
+
+ {% endfilter %}
+
+ {% 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.
+
+ If the class is generic, but the `__init__` method isn't or `merge_init_into_class` is disabled,
+ the class signature is rendered if `separate_signature` and `show_signature_type_parameters` are enabled.
+
+ If the `__init__` method or any overloads are generic, they are rendered as methods if
+ `merge_init_into_class`, `separate_signature` and `show_signature_type_parameters` are enabled.
+ -#}
+ {% if config.merge_init_into_class and "__init__" in all_members %}
+ {% with function = all_members["__init__"] %}
+ {% if function.overloads and config.show_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 and not (config.show_overloads and function.overloads and config.overloads_only) %}
+ {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+ {{ class.name }}
+ {% endfilter %}
+ {% endif %}
+ {% endwith %}
+ {% endif %}
+ {% endblock signature %}
+
+ {% else %}
+ {% if config.show_root_toc_entry %}
+ {% filter heading(heading_level,
+ role="class",
+ id=html_id,
+ toc_label=('
+ {% 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 %}
+
+
+ {% endwith %}
+
+ Bases: {% for expression in class.bases -%}
+
+ {%- with backlink_type = "subclassed-by" -%}
+ {%- include "expression.html.jinja" with context -%}
+ {%- endwith -%}
+ {% if not loop.last %}, {% endif %}
+ {% endfor -%}
+
+ flowchart {{ config.inheritance_diagram_direction }}
+ {{ class.path }}[{{ class.name }}]
+ {% for base in class.mro() %}
+ {{ base.path }}[{{ base.name }}]
+ {% endfor %}
+
+ {{ edges(class) | safe }}
+
+ click {{ class.path }} href "" "{{ class.path }}"
+ {% for base in class.mro() %}
+ click {{ base.path }} href "" "{{ base.path }}"
+ {% endfor %}
+
+ {{ lang.t("Source code in") }}
+ {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
+
+ {% endwith %}
+ {% endif %}
+ {% elif class.source %}
+ {{ lang.t("Source code in") }}
+ {%- if init.relative_filepath.is_absolute() -%}
+ {{ init.relative_package_filepath }}
+ {%- else -%}
+ {{ init.relative_filepath }}
+ {%- endif -%}
+
+ {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
+
+ {{ lang.t("Source code in") }}
+ {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
+
+ {% endif %}
+ {% endif %}
+ {% endblock source %}
+
+ {% block children scoped %}
+ {#- Children block.
+
+ This block renders the children (members) of the class.
+ -#}
+ {% set root = False %}
+ {% set heading_level = heading_level + 1 %}
+ {% include "children.html.jinja" with context %}
+ {% endblock children %}
+ {% endblock contents %}
+ {{ lang.t("Source code in") }}
+ {%- if class.relative_filepath.is_absolute() -%}
+ {{ class.relative_package_filepath }}
+ {%- else -%}
+ {{ class.relative_filepath }}
+ {%- endif -%}
+
+ {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
+
-
\ No newline at end of file
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
new file mode 100644
index 00000000..7f949130
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja
@@ -0,0 +1,20 @@
+{#- Template for admonitions in docstrings.
+
+This template renders admonitions using the `details` HTML element.
+
+Context:
+ section (griffe.DocstringSectionAdmonition): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering admonition") }}
+{% endblock logs %}
+
+{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}
- {{ section.value.contents|convert_markdown(heading_level, html_id) }} -
+
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html
deleted file mode 100644
index 9a1409c0..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html
+++ /dev/null
@@ -1,78 +0,0 @@
-{{ log.debug("Rendering attributes section") }}
-{% if config.docstring_section_style == "table" %}
- {% block table_style %}
- {{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True, autoref_hook=autoref_hook) }}
+ {{ section.value.contents|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} +{{ section.title or "Attributes:" }}
-| Name | -Type | -Description | -
|---|---|---|
{{ attribute.name }} |
-
- {% if attribute.annotation %}
- {% with expression = attribute.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
- {{ attribute.description|convert_markdown(heading_level, html_id) }} | -
{{ section.title or "Attributes:" }}
--
- {% for attribute in section.value %}
-
-
- {{ attribute.name }}
- {% if attribute.annotation %}
- {% with expression = attribute.annotation %}
- (
{% include "expression.html" with context %}) - {% endwith %} - {% endif %} - – {{ attribute.description|convert_markdown(heading_level, html_id) }} -
- {% endfor %}
-
| {{ (section.title or "ATTRIBUTE").rstrip(":").upper() }} | -DESCRIPTION | -
|---|---|
{{ attribute.name }} |
-
- {{ attribute.description|convert_markdown(heading_level, html_id) }}
-
- {% if attribute.annotation %}
-
- TYPE:
- {% with expression = attribute.annotation %}
- |
-
{{ section.title or lang.t("Attributes:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
|
+
+ {% if attribute.annotation %}
+ {% with expression = attribute.annotation %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Attributes:") }}
+-
+ {% for attribute in section.value %}
+
-
+
{{ attribute.name }} {% include "expression.html.jinja" with context %}) + {% endwith %} + {% endif %} + – ++ {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+
+ {% if attribute.annotation %}
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = attribute.annotation %}
+ |
+
{{ section.title or lang.t("Classes:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
|
+
+
+ {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Classes:") }}
+-
+ {% for class in section.value %}
+
-
+
{{ class.name }} + {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("CLASS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or "Examples:" }}
-{% for section_type, sub_section in section.value %} - {% if section_type.value == "text" %} - {{ sub_section|convert_markdown(heading_level, html_id) }} - {% elif section_type.value == "examples" %} - {{ sub_section|highlight(language="pycon", linenums=False) }} - {% endif %} -{% endfor %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja new file mode 100644 index 00000000..32360f7d --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja @@ -0,0 +1,28 @@ +{#- Template for "Examples" sections in docstrings. + +This template renders a list of documented examples. +It alternates between rendering text and code examples. + +Context: + section (griffe.DocstringSectionAttributes): The section to render. +-#} + +{% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} + {{ log.debug("Rendering examples section") }} +{% endblock logs %} + +{% import "language.html.jinja" as lang with context %} +{#- Language module providing the `t` translation method. -#} + +{{ section.title or lang.t("Examples:") }}
+{% for section_type, sub_section in section.value %} + {% if section_type.value == "text" %} + {{ sub_section|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {% elif section_type.value == "examples" %} + {{ sub_section|highlight(language="pycon") }} + {% endif %} +{% endfor %} 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 new file mode 100644 index 00000000..afec8f60 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja @@ -0,0 +1,92 @@ +{#- Template for "Functions" sections in docstrings. + +This template renders a list of documented functions in the format +specified with the [`docstring_section_style`][] configuration option. + +Context: + section (griffe.DocstringSectionAttributes): The section to render. +-#} + +{% block logs scoped %} + {#- Logging block. + + This block can be used to log debug messages, deprecation messages, warnings, etc. + -#} + {{ log.debug("Rendering functions section") }} +{% endblock logs %} + +{% import "language.html.jinja" as lang with context %} +{#- Language module providing the `t` translation method. -#} + +{% if config.docstring_section_style == "table" %} + {% block table_style scoped %} + {#- Block for the `table` section style. -#} +{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
|
+
+
+ {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
+-
+ {% for function in section.value %}
+ {% if not function.name == "__init__" or not config.merge_init_into_class %}
+
-
+
{{ function.name }} + {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endif %}
+ {% endfor %}
+
| {{ (section.title or lang.t("METHOD") if obj.is_class else lang.t("FUNCTION")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Modules:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
|
+
+
+ {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Modules:") }}
+-
+ {% for module in section.value %}
+
-
+
{{ module.name }} + {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("MODULE")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or "Other Parameters:" }}
-| Name | -Type | -Description | -
|---|---|---|
{{ parameter.name }} |
-
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
- {{ parameter.description|convert_markdown(heading_level, html_id) }} | -
{{ section.title or "Other Parameters:" }}
--
- {% for parameter in section.value %}
-
-
- {{ parameter.name }}
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- (
{% include "expression.html" with context %}) - {% endwith %} - {% endif %} - – {{ parameter.description|convert_markdown(heading_level, html_id) }} -
- {% endfor %}
-
| {{ (section.title or "PARAMETER").rstrip(":").upper() }} | -DESCRIPTION | -
|---|---|
{{ parameter.name }} |
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
- {% if parameter.annotation %}
-
- TYPE:
- {% with expression = parameter.annotation %}
- |
-
{{ section.title or lang.t("Other Parameters:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
{{ parameter.name }} |
+
+ {% if parameter.annotation %}
+ {% with expression = parameter.annotation, backlink_type = "used-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Other Parameters:") }}
+-
+ {% for parameter in section.value %}
+
-
+
{{ parameter.name }}+ {% if parameter.annotation %} + {% with expression = parameter.annotation, backlink_type = "used-by" %} + ({% include "expression.html.jinja" with context %}) + {% endwith %} + {% endif %} + – ++ {{ parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
{{ parameter.name }} |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+
+ {% if parameter.annotation %}
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = parameter.annotation, backlink_type = "used-by" %}
+ |
+
{{ section.title or "Parameters:" }}
-| Name | -Type | -Description | -Default | -
|---|---|---|---|
{{ parameter.name }} |
-
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
- {{ parameter.description|convert_markdown(heading_level, html_id) }} | -
- {% if parameter.default %}
- {% with expression = parameter.default %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% else %}
- required
- {% endif %}
- |
-
{{ section.title or "Parameters:" }}
--
- {% for parameter in section.value %}
-
-
- {{ parameter.name }}
- {% if parameter.annotation %}
- {% with expression = parameter.annotation %}
- (
{% include "expression.html" with context %}) - {% endwith %} - {% endif %} - – {{ parameter.description|convert_markdown(heading_level, html_id) }} -
- {% endfor %}
-
| {{ (section.title or "PARAMETER").rstrip(":").upper() }} | -DESCRIPTION | -
|---|---|
{{ parameter.name }} |
-
- {{ parameter.description|convert_markdown(heading_level, html_id) }}
-
- {% if parameter.annotation %}
-
- TYPE:
- {% with expression = parameter.annotation %}
- |
-
{{ section.title or lang.t("Parameters:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +{{ lang.t("Default") }} | +
|---|---|---|---|
+ {% if config.parameter_headings %}
+ {% filter heading(
+ heading_level + 1,
+ role="param",
+ id=html_id ~ "(" ~ parameter.name ~ ")",
+ class="doc doc-heading doc-heading-parameter",
+ toc_label=('{{ parameter.name }}
+ {% endfilter %}
+ {% else %}
+ {{ parameter.name }}
+ {% endif %}
+ |
+
+ {% if parameter.annotation %}
+ {% with expression = parameter.annotation, backlink_type = "used-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
+ {% if parameter.default %}
+ {% with expression = parameter.default, backlink_type = "used-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% else %}
+ {{ lang.t("required") }}
+ {% endif %}
+ |
+
{{ section.title or lang.t("Parameters:") }}
+-
+ {% for parameter in section.value %}
+
-
+ {% if config.parameter_headings %}
+ {% filter heading(
+ heading_level + 1,
+ role="param",
+ id=html_id ~ "(" ~ parameter.name ~ ")",
+ class="doc doc-heading doc-heading-parameter",
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + parameter.name, + skip_inventory=config.skip_local_inventory, + ) %} +{{ parameter.name }}+ {% endfilter %} + {% else %} +{{ parameter.name }}+ {% endif %} + {% if parameter.annotation %} + {% with expression = parameter.annotation, backlink_type = "used-by" %} + ({% include "expression.html.jinja" with context %}+ {%- if parameter.default %}, {{ lang.t("default:") }} + {% with expression = parameter.default, backlink_type = "used-by" %} +{% include "expression.html.jinja" with context %}+ {% endwith %} + {% endif %}) + {% endwith %} + {% endif %} + – ++ {{ parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+ {% if config.parameter_headings %}
+ {% filter heading(
+ heading_level + 1,
+ role="param",
+ id=html_id ~ "(" ~ parameter.name ~ ")",
+ class="doc doc-heading doc-heading-parameter",
+ toc_label=('{{ parameter.name }}
+ {% endfilter %}
+ {% else %}
+ {{ parameter.name }}
+ {% endif %}
+ |
+
+
+ {{ parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+
+ {% if parameter.annotation %}
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = parameter.annotation, backlink_type = "used-by" %}
+ |
+
{{ section.title or "Raises:" }}
-| Type | -Description | -
|---|---|
- {% if raises.annotation %}
- {% with expression = raises.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
- {{ raises.description|convert_markdown(heading_level, html_id) }} | -
{{ section.title or "Raises:" }}
--
- {% for raises in section.value %}
-
-
- {% if raises.annotation %}
- {% with expression = raises.annotation %}
-
{% include "expression.html" with context %}- {% endwith %} - – - {% endif %} - {{ raises.description|convert_markdown(heading_level, html_id) }} -
- {% endfor %}
-
| {{ (section.title or "RAISES").rstrip(":").upper() }} | -DESCRIPTION | -
|---|---|
-
- {% with expression = raises.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- |
- - {{ raises.description|convert_markdown(heading_level, html_id) }} - | -
{{ section.title or lang.t("Raises:") }}
+| {{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|
+ {% if raises.annotation %}
+ {% with expression = raises.annotation, backlink_type = "raised-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ raises.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ lang.t(section.title) or lang.t("Raises:") }}
+-
+ {% for raises in section.value %}
+
-
+ {% if raises.annotation %}
+ {% with expression = raises.annotation, backlink_type = "raised-by" %}
+
{% include "expression.html.jinja" with context %}+ {% endwith %} + – + {% endif %} ++ {{ raises.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("RAISES")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+
+ {% with expression = raises.annotation, backlink_type = "raised-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+
+ |
+
+
+ {{ raises.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or "Receives:" }}
-| Name | {% endif %} -Type | -Description | -
|---|---|---|
{% if receives.name %}{{ receives.name }}{% endif %} | {% endif %}
-
- {% if receives.annotation %}
- {% with expression = receives.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
- {{ receives.description|convert_markdown(heading_level, html_id) }} | -
{{ section.title or "Receives:" }}
--
- {% for receives in section.value %}
-
-
- {% if receives.name %}{{ receives.name }}{% endif %}
- {% if receives.annotation %}
- {% with expression = receives.annotation %}
- {% if receives.name %}({% endif %}
-
{% include "expression.html" with context %}- {% if receives.name %}){% endif %} - {% endwith %} - {% endif %} - – {{ receives.description|convert_markdown(heading_level, html_id) }} -
- {% endfor %}
-
| {{ (section.title or "RECEIVES").rstrip(":").upper() }} | -DESCRIPTION | -
|---|---|
- {% if receives.name %}
- {{ receives.name }}
- {% elif receives.annotation %}
-
- {% with expression = receives.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
- {{ receives.description|convert_markdown(heading_level, html_id) }}
- {% if receives.name and receives.annotation %}
-
-
- TYPE:
- {% with expression = receives.annotation %}
- |
-
{{ section.title or lang.t("Receives:") }}
+| {{ lang.t("Name") }} | {% endif %} +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
{% if receives.name %}{{ receives.name }}{% endif %} | {% endif %}
+
+ {% if receives.annotation %}
+ {% with expression = receives.annotation, backlink_type = "received-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ receives.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Receives:") }}
+-
+ {% for receives in section.value %}
+
-
+ {% if receives.name %}
{{ receives.name }}{% endif %} + {% if receives.annotation %} + {% with expression = receives.annotation, backlink_type = "received-by" %} + {% if receives.name %} ({% endif %} +{% include "expression.html.jinja" with context %}+ {% if receives.name %}){% endif %} + {% endwith %} + {% endif %} + – ++ {{ receives.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("RECEIVES")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+ {% if receives.name %}
+ {{ receives.name }}
+ {% elif receives.annotation %}
+
+ {% with expression = receives.annotation, backlink_type = "received-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ receives.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ {% if receives.name and receives.annotation %}
+
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = receives.annotation, backlink_type = "received-by" %}
+ |
+
{{ section.title or "Returns:" }}
-| Name | {% endif %} -Type | -Description | -
|---|---|---|
{% if returns.name %}{{ returns.name }}{% endif %} | {% endif %}
-
- {% if returns.annotation %}
- {% with expression = returns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
- {{ returns.description|convert_markdown(heading_level, html_id) }} | -
{{ section.title or "Returns:" }}
--
- {% for returns in section.value %}
-
-
- {% if returns.name %}{{ returns.name }}{% endif %}
- {% if returns.annotation %}
- {% with expression = returns.annotation %}
- {% if returns.name %}({% endif %}
-
{% include "expression.html" with context %}- {% if returns.name %}){% endif %} - {% endwith %} - {% endif %} - – {{ returns.description|convert_markdown(heading_level, html_id) }} -
- {% endfor %}
-
| {{ (section.title or "RETURNS").rstrip(":").upper() }} | -DESCRIPTION | -
|---|---|
- {% if returns.name %}
- {{ returns.name }}
- {% elif returns.annotation %}
-
- {% with expression = returns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
- {{ returns.description|convert_markdown(heading_level, html_id) }}
- {% if returns.name and returns.annotation %}
-
-
- TYPE:
- {% with expression = returns.annotation %}
- |
-
{{ section.title or lang.t("Returns:") }}
+| {{ lang.t("Name") }} | {% endif %} +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
{% if returns.name %}{{ returns.name }}{% endif %} | {% endif %}
+
+ {% if returns.annotation %}
+ {% with expression = returns.annotation, backlink_type = "returned-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ returns.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Returns:") }}
+-
+ {% for returns in section.value %}
+
-
+ {% if returns.name %}
{{ returns.name }}{% endif %} + {% if returns.annotation %} + {% with expression = returns.annotation, backlink_type = "returned-by" %} + {% if returns.name %} ({% endif %} +{% include "expression.html.jinja" with context %}+ {% if returns.name %}){% endif %} + {% endwith %} + {% endif %} + – ++ {{ returns.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION").upper() }} | +
|---|---|
+ {% if returns.name %}
+ {{ returns.name }}
+ {% elif returns.annotation %}
+
+ {% with expression = returns.annotation, backlink_type = "returned-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ returns.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ {% if returns.name and returns.annotation %}
+
+
+ {{ lang.t("TYPE:") }}
+ {% with expression = returns.annotation, backlink_type = "returned-by" %}
+ |
+
{{ section.title or lang.t("Type Aliases:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
|
+
+
+ {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Type Aliases:") }}
+-
+ {% for type_alias in section.value %}
+
-
+
{{ type_alias.name }} + {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("TYPE ALIAS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
+ + {{ section.title or lang.t(("Class " if obj.is_class else "Init " if obj.is_init_method else "") ~ "Type Parameters:") }} + +
+| {{ lang.t("Name") }} | +{{ lang.t("Bound or Constraints") }} | +{{ lang.t("Description") }} | +{{ lang.t("Default") }} | +
|---|---|---|---|
+ {% if config.type_parameter_headings %}
+ {% filter heading(
+ heading_level + 1,
+ role="typeparam",
+ id=obj.path ~ "[" ~ type_parameter.name ~ "]",
+ class="doc doc-heading doc-heading-type_parameter",
+ toc_label=('{{ type_parameter.name }}
+ {% endfilter %}
+ {% else %}
+ {{ type_parameter.name }}
+ {% endif %}
+ |
+
+ {% if type_parameter.annotation %}
+ {% with expression = type_parameter.annotation %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ type_parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
+ {% if type_parameter.default %}
+ {% with expression = type_parameter.default %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% else %}
+ {{ lang.t("required") }}
+ {% endif %}
+ |
+
+ + {{ section.title or lang.t(("Class " if obj.is_class else "Init " if obj.is_init_method else "") ~ "Type Parameters:") }} + +
+-
+ {% for type_parameter in section.value %}
+
-
+ {% if config.type_parameter_headings %}
+ {% filter heading(
+ heading_level + 1,
+ role="typeparam",
+ id=obj.path ~ "[" ~ type_parameter.name ~ "]",
+ class="doc doc-heading doc-heading-type_parameter",
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + type_parameter.name, + ) %} +{{ type_parameter.name }}+ {% endfilter %} + {% else %} +{{ type_parameter.name }}+ {% endif %} + {%- if type_parameter.bound or type_parameter.constraints or type_parameter.default -%} + ( + {%- endif -%} + {%- if type_parameter.bound -%} + {%- with expression = type_parameter.bound -%} +{% include "expression.html.jinja" with context %}+ {%- endwith -%} + {%- if type_parameter.default %}, {% endif -%} + {%- elif type_parameter.constraints -%} + {%- for expression in type_parameter.constraints -%} +{% include "expression.html.jinja" with context %}+ {%- if not loop.last %}, {% endif -%} + {%- endfor -%} + {%- if type_parameter.default %}, {% endif -%} + {%- endif -%} + {%- if type_parameter.default -%} + {{ lang.t("default:") }} + {% with expression = type_parameter.default %} +{% include "expression.html.jinja" with context %}+ {%- endwith -%} + {%- endif -%} + {%- if type_parameter.constraints or type_parameter.default -%} + ) + {% endif -%} + – ++ {{ type_parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| + + {{ (section.title or lang.t(("CLASS " if obj.is_class else "INIT " if obj.is_init_method else "") ~ "TYPE PARAMETER")).rstrip(":").upper() }} + + | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+ {% if config.type_parameter_headings %}
+ {% filter heading(
+ heading_level + 1,
+ role="typeparam",
+ id=obj.path ~ "[" ~ type_parameter.name ~ "]",
+ class="doc doc-heading doc-heading-type_parameter",
+ toc_label=('{{ type_parameter.name }}
+ {% endfilter %}
+ {% else %}
+ {{ type_parameter.name }}
+ {% endif %}
+ |
+
+
+ {{ type_parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+
+ {% if type_parameter.constraints %}
+
+ {{ lang.t("CONSTRAINTS:") }}
+ {% for constraint in type_parameter.constraints -%}
+ {%- with expression = constraint -%}
+ |
+
{{ section.title or "Warns:" }}
-| Type | -Description | -
|---|---|
- {% if warns.annotation %}
- {% with expression = warns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
- {{ warns.description|convert_markdown(heading_level, html_id) }} | -
{{ section.title or "Warns:" }}
--
- {% for warns in section.value %}
-
-
- {% if warns.annotation %}
- {% with expression = warns.annotation %}
-
{% include "expression.html" with context %}- {% endwith %} - – - {% endif %} - {{ warns.description|convert_markdown(heading_level, html_id) }} -
- {% endfor %}
-
| {{ (section.title or "WARNS").rstrip(":").upper() }} | -DESCRIPTION | -
|---|---|
-
- {% with expression = warns.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- |
- - {{ warns.description|convert_markdown(heading_level, html_id) }} - | -
{{ section.title or lang.t("Warns:") }}
+| {{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|
+ {% if warns.annotation %}
+ {% with expression = warns.annotation, backlink_type = "emitted-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ warns.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Warns:") }}
+-
+ {% for warns in section.value %}
+
-
+ {% if warns.annotation %}
+ {% with expression = warns.annotation, backlink_type = "emitted-by" %}
+
{% include "expression.html.jinja" with context %}+ {% endwith %} + – + {% endif %} ++ {{ warns.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("WARNS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+
+ {% with expression = warns.annotation, backlink_type = "emitted-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+
+ |
+
+
+ {{ warns.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or "Yields:" }}
-| Name | {% endif %} -Type | -Description | -
|---|---|---|
{% if yields.name %}{{ yields.name }}{% endif %} | {% endif %}
-
- {% if yields.annotation %}
- {% with expression = yields.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
- {% endif %}
- |
- {{ yields.description|convert_markdown(heading_level, html_id) }} | -
{{ section.title or "Yields:" }}
--
- {% for yields in section.value %}
-
-
- {% if yields.name %}{{ yields.name }}{% endif %}
- {% if yields.annotation %}
- {% with expression = yields.annotation %}
- {% if yields.name %}({% endif %}
-
{% include "expression.html" with context %}- {% if yields.name %}){% endif %} - {% endwith %} - {% endif %} - – {{ yields.description|convert_markdown(heading_level, html_id) }} -
- {% endfor %}
-
| {{ (section.title or "YIELDS").rstrip(":").upper() }} | -DESCRIPTION | -
|---|---|
- {% if yields.name %}
- {{ yields.name }}
- {% elif yields.annotation %}
-
- {% with expression = yields.annotation %}
- {% include "expression.html" with context %}
- {% endwith %}
-
- {% endif %}
- |
-
- {{ yields.description|convert_markdown(heading_level, html_id) }}
- {% if yields.name and yields.annotation %}
-
-
- TYPE:
- {% with expression = yields.annotation %}
- |
-
{{ section.title or lang.t("Yields:") }}
+| {{ lang.t("Name") }} | {% endif %} +{{ lang.t("Type") }} | +{{ lang.t("Description") }} | +
|---|---|---|
{% if yields.name %}{{ yields.name }}{% endif %} | {% endif %}
+
+ {% if yields.annotation %}
+ {% with expression = yields.annotation, backlink_type = "yielded-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ yields.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Yields:") }}
+-
+ {% for yields in section.value %}
+
-
+ {% if yields.name %}
{{ yields.name }}{% endif %} + {% if yields.annotation %} + {% with expression = yields.annotation, backlink_type = "yielded-by" %} + {% if yields.name %} ({% endif %} +{% include "expression.html.jinja" with context %}+ {% if yields.name %}){% endif %} + {% endwith %} + {% endif %} + – ++ {{ yields.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} ++
+ {% endfor %}
+
| {{ (section.title or lang.t("YIELDS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
+ {% if yields.name %}
+ {{ yields.name }}
+ {% elif yields.annotation %}
+
+ {% with expression = yields.annotation, backlink_type = "yielded-by" %}
+ {% include "expression.html.jinja" with context %}
+ {% endwith %}
+
+ {% endif %}
+ |
+
+
+ {{ yields.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ {% if yields.name and yields.annotation %}
+
+
+ {{ lang.t("TYPE:") }}:
+ {% with expression = yields.annotation, backlink_type = "yielded-by" %}
+ |
+
-{% with html_id = function.path %}
-
- {% if root %}
- {% set show_full_path = config.show_root_full_path %}
- {% set root_members = True %}
- {% elif root_members %}
- {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
- {% set root_members = False %}
- {% else %}
- {% set show_full_path = config.show_object_full_path %}
- {% endif %}
-
- {% if not root or config.show_root_heading %}
-
- {% filter heading(heading_level,
- role="function",
- id=html_id,
- class="doc doc-heading",
- toc_label=function.name ~ "()") %}
-
- {% if config.separate_signature %}
- {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
- {% else %}
- {% filter highlight(language="python", inline=True) %}
- {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
- {% include "signature.html" with context %}
- {% endfilter %}
- {% endif %}
-
- {% with labels = function.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
-
- {% endfilter %}
-
- {% if config.separate_signature %}
- {% filter highlight(language="python", inline=False) %}
- {% filter format_signature(config.line_length) %}
- {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
- {% include "signature.html" with context %}
- {% endfilter %}
- {% endfilter %}
- {% endif %}
-
- {% else %}
- {% if config.show_root_toc_entry %}
- {% filter heading(heading_level,
- role="function",
- id=html_id,
- toc_label=function.path if config.show_root_full_path else function.name,
- hidden=True) %}
- {% endfilter %}
- {% endif %}
- {% set heading_level = heading_level - 1 %}
- {% endif %}
-
-
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
new file mode 100644
index 00000000..3cfc7f30
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
@@ -0,0 +1,164 @@
+{#- Template for Python functions.
+
+This template renders a Python function or method.
+
+Context:
+ function (griffe.Function): The function to render.
+ root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+ heading_level (int): The HTML heading level to use.
+ config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering " + function.path) }}
+{% endblock logs %}
+
+{% import "language.html.jinja" as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+
- {% with docstring_sections = function.docstring.parsed %}
- {% include "docstring.html" with context %}
- {% endwith %}
-
- {% if config.show_source and function.source %}
-
-
-{% endwith %}
-
- Source code in
- {{ function.source|highlight(language="python", linestart=function.lineno, linenums=True) }}
-
- {% endif %}
- Source code in {{ function.relative_filepath }}
- {{ function.source|highlight(language="python", linestart=function.lineno, linenums=True) }}
-
+ {% with obj = function, html_id = function.path %}
+
+ {% if root %}
+ {% set show_full_path = config.show_root_full_path %}
+ {% set root_members = True %}
+ {% elif root_members %}
+ {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+ {% set root_members = False %}
+ {% else %}
+ {% set show_full_path = config.show_object_full_path %}
+ {% endif %}
+
+ {% set function_name = function.path if show_full_path else function.name %}
+ {#- Brief or full function name depending on configuration. -#}
+ {% set symbol_type = "method" if function.parent.is_class else "function" %}
+ {#- Symbol type: method when parent is a class, function otherwise. -#}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="function",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=(('
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html
deleted file mode 100644
index 4f2f72d9..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html
+++ /dev/null
@@ -1,8 +0,0 @@
-{% if labels %}
- {{ log.debug("Rendering labels") }}
-
- {% for label in labels %}
-
+ {% for overload in function.overloads %}
+ {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %}
+ {{ overload.name }}
+ {% endfilter %}
+ {% endfor %}
+
+ {% endif %}
+ {% if config.separate_signature and not (config.show_overloads and function.overloads and config.overloads_only) %}
+ {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+ {{ function.name }}
+ {% endfilter %}
+ {% endif %}
+ {% endblock signature %}
+
+ {% else %}
+
+ {% if config.show_root_toc_entry %}
+ {% filter heading(
+ heading_level,
+ role="function",
+ id=html_id,
+ toc_label=(('
+ {% 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 %}
+ {% include "docstring.html.jinja" with context %}
+ {% endwith %}
+ {% endblock docstring %}
+
+ {% if config.backlinks %}
+
+
+ {% endwith %}
+
+ {{ lang.t("Source code in") }}
+ {{ function.source|highlight(language="python", linestart=function.lineno or 0, linenums=True) }}
+
+ {% endif %}
+ {% endblock source %}
+ {% endblock contents %}
+ {{ lang.t("Source code in") }}
+ {%- if function.relative_filepath.is_absolute() -%}
+ {{ function.relative_package_filepath }}
+ {%- else -%}
+ {{ function.relative_filepath }}
+ {%- endif -%}
+
+ {{ function.source|highlight(language="python", linestart=function.lineno or 0, linenums=True) }}
+ {{ label }}
- {% endfor %}
-
-{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
new file mode 100644
index 00000000..bbd3a7c1
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html.jinja
@@ -0,0 +1,25 @@
+{#- Template for object labels.
+
+Labels are additional information that can be displayed alongside an object.
+Example labels include "property", "writable" or "cached" for properties,
+"classmethod" or "staticmethod" for methods, etc.
+
+Context:
+ labels (list): The list of labels to render.
+ config (dict): The configuration options.
+-#}
+
+{% if config.show_labels and labels %}
+ {% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering labels") }}
+ {% endblock logs %}
+
+ {% for label in labels|sort %}
+ {{ label }}
+ {% endfor %}
+
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
new file mode 100644
index 00000000..31ecfdd6
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
@@ -0,0 +1,18 @@
+{#- Import translation macros for the given language and fallback language. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% set lang_pth = "languages/" ~ locale ~ ".html.jinja" %}
+{% if lang_pth is existing_template %}
+ {% import lang_pth as lang %}
+ {% import "languages/en.html.jinja" as fallback %}
+ {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %}
+{% else %}
+ {% import "languages/en.html.jinja" as lang %}
+ {% macro t(key) %}{{ lang.t(key) }}{% endmacro %}
+{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja
new file mode 100644
index 00000000..d2bbba03
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html.jinja
@@ -0,0 +1,61 @@
+{#- Macro for English translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "ATTRIBUTE",
+ "Attributes": "Attributes",
+ "Attributes:": "Attributes:",
+ "BOUND:": "BOUND:",
+ "Bound or Constraints": "Bound or Constraints",
+ "Classes": "Classes",
+ "Classes:": "Classes:",
+ "Class Type Parameters:": "Class Type Parameters:",
+ "CLASS TYPE PARAMETER": "CLASS TYPE PARAMETER",
+ "CLASS": "CLASS",
+ "CONSTRAINTS:": "CONSTRAINTS:",
+ "DEFAULT:": "DEFAULT:",
+ "Default": "Default",
+ "default:": "default:",
+ "DESCRIPTION": "DESCRIPTION",
+ "Description": "Description",
+ "Examples:": "Examples:",
+ "Functions": "Functions",
+ "Functions:": "Functions:",
+ "FUNCTION": "FUNCTION",
+ "Init Type Parameters:": "Init Type Parameters:",
+ "INIT TYPE PARAMETER": "INIT TYPE PARAMETER",
+ "Methods:": "Methods:",
+ "METHOD": "METHOD",
+ "Modules": "Modules",
+ "Modules:": "Modules:",
+ "MODULE": "MODULE",
+ "Name": "Name",
+ "Other Parameters:": "Other Parameters:",
+ "PARAMETER": "PARAMETER",
+ "Parameters:": "Parameters:",
+ "RAISES": "RAISES",
+ "Raises:" : "Raises:",
+ "RECEIVES": "RECEIVES",
+ "Receives:": "Receives:",
+ "required": "required",
+ "RETURNS": "RETURNS",
+ "Returns:": "Returns:",
+ "Source code in": "Source code in",
+ "TYPE:": "TYPE:",
+ "Type": "Type",
+ "Type Aliases": "Type Aliases",
+ "Type Aliases:": "Type Aliases:",
+ "TYPE ALIAS": "TYPE ALIAS",
+ "Type Parameters:": "Type Parameters:",
+ "TYPE PARAMETER": "TYPE PARAMETER",
+ "WARNS": "WARNS",
+ "Warns:": "Warns:",
+ "YIELDS": "YIELDS",
+ "Yields:": "Yields:",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja
new file mode 100644
index 00000000..840da89c
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja
@@ -0,0 +1,61 @@
+{#- Macro for Japanese translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "属性",
+ "Attributes": "属性",
+ "Attributes:": "属性：",
+ "BOUND:": "境界：",
+ "Bound or Constraints": "境界や制約",
+ "Classes": "クラス",
+ "Classes:": "クラス：",
+ "Class Type Parameters:": "Class Type Parameters:",
+ "CLASS TYPE PARAMETER": "CLASS TYPE PARAMETER",
+ "CLASS": "クラス",
+ "CONSTRAINTS:": "制約：",
+ "DEFAULT:": "デフォルト：",
+ "Default": "デフォルト",
+ "default:": "デフォルト：",
+ "DESCRIPTION": "デスクリプション",
+ "Description": "デスクリプション",
+ "Examples:": "例：",
+ "Functions": "関数",
+ "Functions:": "関数：",
+ "FUNCTION": "関数",
+ "Init Type Parameters:": "Init Type Parameters:",
+ "INIT TYPE PARAMETER": "INIT TYPE PARAMETER",
+ "Methods:": "メソッド：",
+ "METHOD": "メソッド",
+ "Modules": "モジュール",
+ "Modules:": "モジュール：",
+ "MODULE": "モジュール",
+ "Name": "名前",
+ "Other Parameters:": "他の引数：",
+ "PARAMETER": "引数",
+ "Parameters:": "引数：",
+ "RAISES": "発生",
+ "Raises:" : "発生：",
+ "RECEIVES": "取得",
+ "Receives:": "取得：",
+ "required": "必須",
+ "RETURNS": "戻り値",
+ "Returns:": "戻り値：",
+ "Source code in": "ソースコード位置：",
+ "TYPE:": "タイプ：",
+ "Type": "タイプ",
+ "Type Aliases": "型エイリアス",
+ "Type Aliases:": "型エイリアス：",
+ "TYPE ALIAS": "型エイリアス",
+ "Type Parameters:": "型パラメータ：",
+ "TYPE PARAMETER": "型パラメータ",
+ "WARNS": "警告",
+ "Warns:": "警告：",
+ "YIELDS": "返す",
+ "Yields:": "返す：",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja
new file mode 100644
index 00000000..53888779
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja
@@ -0,0 +1,61 @@
+{#- Macro for Chinese translations. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% macro t(key) %}{{ {
+ "ATTRIBUTE": "属性",
+ "Attributes": "属性",
+ "Attributes:": "属性：",
+ "BOUND:": "边界：",
+ "Bound or Constraints": "边界或约束",
+ "Classes": "类",
+ "Classes:": "类：",
+ "Class Type Parameters:": "Class Type Parameters:",
+ "CLASS TYPE PARAMETER": "CLASS TYPE PARAMETER",
+ "CLASS": "类",
+ "CONSTRAINTS:": "约束：",
+ "DEFAULT:": "默认：",
+ "Default": "默认",
+ "default:": "默认：",
+ "DESCRIPTION": "描述",
+ "Description": "描述",
+ "Examples:": "示例：",
+ "Functions": "函数",
+ "Functions:": "函数：",
+ "FUNCTION": "函数",
+ "Init Type Parameters:": "Init Type Parameters:",
+ "INIT TYPE PARAMETER": "INIT TYPE PARAMETER",
+ "Methods:": "方法：",
+ "METHOD": "方法",
+ "Modules": "模块",
+ "Modules:": "模块：",
+ "MODULE": "模块",
+ "Name": "名称",
+ "Other Parameters:": "其他参数：",
+ "PARAMETER": "参数",
+ "Parameters:": "参数：",
+ "RAISES": "引发",
+ "Raises:" : "引发：",
+ "Receives:": "接收：",
+ "RECEIVES": "接收",
+ "required": "必需",
+ "RETURNS": "返回",
+ "Returns:": "返回：",
+ "Source code in": "源代码位于：",
+ "TYPE:": "类型：",
+ "Type": "类型",
+ "Type Aliases": "类型别名",
+ "Type Aliases:": "类型别名：",
+ "TYPE ALIAS": "类型别名",
+ "Type Parameters:": "类型形参：",
+ "TYPE PARAMETER": "类型形参",
+ "Warns:": "警告：",
+ "WARNS": "警告",
+ "YIELDS": "产生",
+ "Yields:": "产生：",
+}[key] }}{% endmacro %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html b/src/mkdocstrings_handlers/python/templates/material/_base/module.html
deleted file mode 100644
index 8e14d354..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html
+++ /dev/null
@@ -1,63 +0,0 @@
-{{ log.debug("Rendering " + module.path) }}
-
-
-{% with html_id = module.path %}
-
- {% if root %}
- {% set show_full_path = config.show_root_full_path %}
- {% set root_members = True %}
- {% elif root_members %}
- {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
- {% set root_members = False %}
- {% else %}
- {% set show_full_path = config.show_object_full_path %}
- {% endif %}
-
- {% if not root or config.show_root_heading %}
-
- {% filter heading(heading_level,
- role="module",
- id=html_id,
- class="doc doc-heading",
- toc_label=module.name) %}
-
- {% with module_name = module.path if show_full_path else module.name %}
- {% if config.separate_signature %}
- {{ module_name }}
- {% else %}
-
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
new file mode 100644
index 00000000..c0f4a7cb
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
@@ -0,0 +1,129 @@
+{#- Template for Python modules.
+
+This template renders a Python module.
+
+Context:
+ module (griffe.Module): The module to render.
+ root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+ heading_level (int): The HTML heading level to use.
+ config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering " + module.path) }}
+{% endblock logs %}
+
+{{ module_name }}
- {% endif %}
- {% endwith %}
-
- {% with labels = module.labels %}
- {% include "labels.html" with context %}
- {% endwith %}
-
- {% endfilter %}
-
- {% else %}
- {% if config.show_root_toc_entry %}
- {% filter heading(heading_level,
- role="module",
- id=html_id,
- toc_label=module.path if config.show_root_full_path else module.name,
- hidden=True) %}
- {% endfilter %}
- {% endif %}
- {% set heading_level = heading_level - 1 %}
- {% endif %}
-
-
- {% with docstring_sections = module.docstring.parsed %}
- {% include "docstring.html" with context %}
- {% endwith %}
-
- {% with obj = module %}
- {% set root = False %}
- {% set heading_level = heading_level + 1 %}
- {% include "children.html" with context %}
- {% endwith %}
-
-
-{% endwith %}
-
+ {% with obj = module, html_id = module.path %}
+
+ {% if root %}
+ {% set show_full_path = config.show_root_full_path %}
+ {% set root_members = True %}
+ {% elif root_members %}
+ {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+ {% set root_members = False %}
+ {% else %}
+ {% set show_full_path = config.show_object_full_path %}
+ {% endif %}
+
+ {% set module_name = module.path if show_full_path else module.name %}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="module",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=('
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html
deleted file mode 100644
index d571c73e..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html
+++ /dev/null
@@ -1,47 +0,0 @@
-{%- if config.show_signature -%}
- {{ log.debug("Rendering signature") }}
- {%- with -%}
-
- {%- set ns = namespace(has_pos_only=False, render_pos_only_separator=True, render_kw_only_separator=True, equal="=") -%}
-
- {%- if config.show_signature_annotations -%}
- {%- set ns.equal = " = " -%}
- {%- endif -%}
-
- (
- {%- for parameter in function.parameters -%}
- {%- if parameter.name not in ("self", "cls") or loop.index0 > 0 or not (function.parent and function.parent.is_class) -%}
-
- {%- if parameter.kind.value == "positional-only" -%}
- {%- set ns.has_pos_only = True -%}
- {%- else -%}
- {%- if ns.has_pos_only and ns.render_pos_only_separator -%}
- {%- set ns.render_pos_only_separator = False %}/, {% endif -%}
- {%- if parameter.kind.value == "keyword-only" -%}
- {%- if ns.render_kw_only_separator -%}
- {%- set ns.render_kw_only_separator = False %}*, {% endif -%}
- {%- endif -%}
- {%- endif -%}
-
- {%- if config.show_signature_annotations and parameter.annotation is not none -%}
- {%- set annotation = ": " + parameter.annotation|safe -%}
- {%- endif -%}
-
- {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%}
- {%- set default = ns.equal + parameter.default|safe -%}
- {%- endif -%}
-
- {%- if parameter.kind.value == "variadic positional" -%}
- {%- set ns.render_kw_only_separator = False -%}
- {%- endif -%}
-
- {{ parameter.name }}{{ annotation }}{{ default }}
- {%- if not loop.last %}, {% endif -%}
-
- {%- endif -%}
- {%- endfor -%}
- )
- {%- if config.show_signature_annotations and function.annotation %} -> {{ function.annotation|safe }}{%- endif -%}
-
- {%- endwith -%}
-{%- endif -%}
\ No newline at end of file
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
new file mode 100644
index 00000000..7167f1d7
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja
@@ -0,0 +1,135 @@
+{#- Template for signatures.
+
+This template renders the signature of a function or method.
+It iterates over the parameters of the function to rebuild the signature.
+The signature is the list of parameters of a function or method, including their names, default values, and annotations.
+
+Context:
+ function (griffe.Function): The function or method to render.
+ config (dict): The configuration options.
+-#}
+
+{%- 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") }}
+ {%- endblock logs -%}
+ {%- with -%}
+
+ {%- set ns = namespace(
+ has_pos_only=False,
+ render_pos_only_separator=True,
+ render_kw_only_separator=True,
+ annotation="",
+ equal="=",
+ default=False,
+ ) -%}
+
+ (
+ {%- for parameter in function.parameters -%}
+ {%- if parameter.name not in ("self", "cls") or loop.index0 > 0 or not (function.parent and function.parent.is_class) -%}
+
+ {#- Handle parameter kind. -#}
+ {%- if parameter.kind.value == "positional-only" -%}
+ {%- set ns.has_pos_only = True -%}
+ {%- else -%}
+ {%- if ns.has_pos_only and ns.render_pos_only_separator -%}
+ {%- set ns.render_pos_only_separator = False %}/, {% endif -%}
+ {%- if parameter.kind.value == "keyword-only" -%}
+ {%- if ns.render_kw_only_separator -%}
+ {%- set ns.render_kw_only_separator = False %}*, {% endif -%}
+ {%- endif -%}
+ {%- endif -%}
+
+ {#- Prepare type annotation. -#}
+ {%- if config.show_signature_annotations and parameter.annotation is not none -%}
+ {%- set ns.equal = " = " -%}
+ {%- if config.separate_signature -%}
+ {%- with expression = parameter.annotation -%}
+ {%- set ns.annotation -%}: {% with backlink_type = "used-by" -%}
+ {%- include "expression.html.jinja" with context -%}
+ {%- endwith -%}{%- endset -%}
+ {%- endwith -%}
+ {%- else -%}
+ {%- set ns.annotation = ": " + parameter.annotation|safe -%}
+ {%- endif -%}
+ {%- else -%}
+ {%- set ns.equal = "=" -%}
+ {%- set ns.annotation = "" -%}
+ {%- endif -%}
+
+ {#- Prepare default value. -#}
+ {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%}
+ {%- set ns.default = True -%}
+ {%- else -%}
+ {%- set ns.default = False -%}
+ {%- endif -%}
+
+ {#- TODO: Move inside kind handling above? -#}
+ {%- if parameter.kind.value == "variadic positional" -%}
+ {%- set ns.render_kw_only_separator = False -%}
+ {%- endif -%}
+
+ {#- Prepare name. -#}
+ {%- set param_prefix -%}
+ {%- if parameter.kind.value == "variadic positional" -%}
+ *
+ {%- elif parameter.kind.value == "variadic keyword" -%}
+ **
+ {%- endif -%}
+ {%- 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=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 -%}
+ {{ module_name }}
+ {% endif %}
+ {% endblock heading %}
+
+ {% block labels scoped %}
+ {#- Labels block.
+
+ This block renders the labels for the module.
+ -#}
+ {% with labels = module.labels %}
+ {% include "labels.html.jinja" with context %}
+ {% endwith %}
+ {% endblock labels %}
+
+ {% endfilter %}
+
+ {% else %}
+ {% if config.show_root_toc_entry %}
+ {% filter heading(heading_level,
+ role="module",
+ id=html_id,
+ toc_label=('
+ {% 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 %}
+ {% include "docstring.html.jinja" with context %}
+ {% endwith %}
+ {% endblock docstring %}
+
+ {% if config.backlinks %}
+
+
+ {% endwith %}
+
+ {% with obj = type_alias, html_id = type_alias.path %}
+
+ {% if root %}
+ {% set show_full_path = config.show_root_full_path %}
+ {% set root_members = True %}
+ {% elif root_members %}
+ {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+ {% set root_members = False %}
+ {% else %}
+ {% set show_full_path = config.show_object_full_path %}
+ {% endif %}
+
+ {% set type_alias_name = type_alias.path if show_full_path else type_alias.name %}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="typealias",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=('
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/type_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/type_parameters.html.jinja
new file mode 100644
index 00000000..47100924
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/type_parameters.html.jinja
@@ -0,0 +1,87 @@
+{#- Template for type parameters.
+
+This template renders the type parameters of a generic obj.
+It iterates over the type parameters of the object to rebuild the signature.
+The signature is the list of type parameters of a generic object, including their names, default values, and bound or constraints.
+
+Context:
+ obj (griffe.Object): The object to render.
+ config (dict): The configuration options.
+-#}
+
+{%- if config.show_signature_type_parameters -%}
+ {%- block logs scoped -%}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug("Rendering type parameters") }}
+ {%- endblock logs -%}
+
+ {%- with ns = namespace(annotation="", equal="=", default=False) -%}
+ {%- if obj.is_generic -%}
+ [
+ {%- for type_parameter in obj.type_parameters -%}
+ {#- Prepare type bound or constraints. -#}
+ {%- if config.show_signature_annotations and type_parameter.annotation is not none -%}
+ {%- set ns.equal = " = " -%}
+ {%- if config.separate_signature and config.signature_crossrefs -%}
+ {%- with expression = type_parameter.annotation -%}
+ {%- set ns.annotation -%}: {% include "expression.html.jinja" with context %}{%- endset -%}
+ {%- endwith -%}
+ {%- else -%}
+ {%- set ns.annotation = ": " + type_parameter.annotation|safe -%}
+ {%- endif -%}
+ {%- else -%}
+ {%- set ns.equal = "=" -%}
+ {%- set ns.annotation = "" -%}
+ {%- endif -%}
+
+ {#- Prepare default value. -#}
+ {%- if type_parameter.default is not none -%}
+ {%- set ns.default = True -%}
+ {%- else -%}
+ {%- set ns.default = False -%}
+ {%- endif -%}
+
+ {#- Prepare name. -#}
+ {%- set type_param_prefix -%}
+ {%- if type_parameter.kind == "type-var-tuple" -%}
+ *
+ {%- elif type_parameter.kind == "param-spec" -%}
+ **
+ {%- endif -%}
+ {%- endset -%}
+
+ {#- Render type parameter name with optional cross-reference to its heading. -#}
+ {{ type_param_prefix }}
+ {%- if config.separate_signature and config.type_parameter_headings and config.signature_crossrefs -%}
+ {%- filter stash_crossref(length=type_parameter.name|length) -%}
+
+ {% block contents scoped %}
+ {#- Contents block.
+
+ This block renders the contents of the type alias.
+ 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 type alias.
+ -#}
+ {% with docstring_sections = type_alias.docstring.parsed %}
+ {% include "docstring.html.jinja" with context %}
+ {% endwith %}
+ {% endblock docstring %}
+ {% endblock contents %}
+
+
+ {% endwith %}
+-
-
- Exceptions: - {% for exception in exceptions %} -
- {{ ("`" + exception.annotation + "`: " + exception.description)|convert_markdown(heading_level, html_id) }} - {% endfor %} -
-
-
- Keyword arguments: - {% for kwarg in kwargs %} -
- {{ ("**" + kwarg.name + ":** " + ("`" + kwarg.annotation + "` – " if kwarg.annotation else "") + kwarg.description)|convert_markdown(heading_level, html_id) }} - {% endfor %} -
-
-
- Arguments: - {% for parameter in parameters %} -
- {{ ("**" + parameter.name + ":** " + ("`" + parameter.annotation + "` – " if parameter.annotation else "") + parameter.description)|convert_markdown(heading_level, html_id) }} - {% endfor %} -
-
-
- Returns: -
- {{ (("`" + return.annotation + "` – " if return.annotation else "") + return.description)|convert_markdown(heading_level, html_id) }} -
-
-
- Yields: -
- {{ (("`" + yield.annotation + "` – " if yield.annotation else "") + yield.description)|convert_markdown(heading_level, html_id) }} -
+ {% with obj = class, html_id = class.path %}
+
+ {% if root %}
+ {% set show_full_path = config.show_root_full_path %}
+ {% set root_members = True %}
+ {% elif root_members %}
+ {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+ {% set root_members = False %}
+ {% else %}
+ {% set show_full_path = config.show_object_full_path %}
+ {% endif %}
+
+ {% set class_name = class.path if show_full_path else class.name %}
+
+ {% if not root or config.show_root_heading %}
+ {% filter heading(
+ heading_level,
+ role="class",
+ id=html_id,
+ class="doc doc-heading",
+ toc_label=('
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
new file mode 100644
index 00000000..a3817449
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja
@@ -0,0 +1,49 @@
+{#- Template for "Attributes" sections in docstrings.
+
+This template renders a list of documented attributes in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+ section (griffe.DocstringSectionAttributes): The section to render.
+-#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+ {{ log.debug() }}
+{% endblock %}
+
+{% import "language.html.jinja" as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{{ class_name }}
+ {% endif %}
+ {% endblock heading %}
+
+ {% block labels scoped %}
+ {#- Labels block.
+
+ This block renders the labels for the class.
+ -#}
+ {% with labels = class.labels %}
+ {% include "labels.html.jinja" with context %}
+ {% endwith %}
+ {% endblock labels %}
+
+ {% endfilter %}
+
+ {% block signature scoped %}
+ {#- Signature block.
+
+ This block renders the signature for the class.
+ -#}
+ {% if config.separate_signature and config.merge_init_into_class %}
+ {% if "__init__" in class.all_members %}
+ {% with function = class.all_members["__init__"] %}
+ {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+ {{ class.name }}
+ {% endfilter %}
+ {% endwith %}
+ {% endif %}
+ {% endif %}
+ {% endblock signature %}
+
+ {% else %}
+ {% if config.show_root_toc_entry %}
+ {% filter heading(heading_level,
+ role="class",
+ id=html_id,
+ toc_label=('
+ {% 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 %}
+
+
+ {% endwith %}
+
+
+ Bases: {% for expression in class.bases -%}
+ {% include "expression.html.jinja" with context %}{% if not loop.last %}, {% endif %}
+ {% endfor -%}
+
+ flowchart {{ config.inheritance_diagram_direction }}
+ {{ class.path }}[{{ class.name }}]
+ {% for base in class.mro() %}
+ {{ base.path }}[{{ base.name }}]
+ {% endfor %}
+
+ {{ edges(class) | safe }}
+
+ click {{ class.path }} href "" "{{ class.path }}"
+ {% for base in class.mro() %}
+ click {{ base.path }} href "" "{{ base.path }}"
+ {% endfor %}
+
+
+ {% endif %}
+ {% endblock inheritance_diagram %}
+
+ {% block docstring scoped %}
+ {#- Docstring block.
+
+ This block renders the docstring for the class.
+ -#}
+ {% with docstring_sections = class.docstring.parsed %}
+ {% include "docstring.html.jinja" 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__"] %}
+ {% with obj = function, docstring_sections = function.docstring.parsed %}
+ {% include "docstring.html.jinja" with context %}
+ {% endwith %}
+ {% endwith %}
+ {% endif %}
+ {% endif %}
+ {% endblock docstring %}
+
+ {% block summary scoped %}
+ {#- Summary block.
+
+ This block renders auto-summaries for classes, methods, and attributes.
+ -#}
+ {% include "summary.html.jinja" with context %}
+ {% endblock summary %}
+
+ {% block source scoped %}
+ {#- Source block.
+
+ This block renders the source code for the class.
+ -#}
+ {% 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__"] %}
+
+ Source code in
+ {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
+
+ {% endwith %}
+ {% endif %}
+ {% elif class.source %}
+ Source code in
+ {%- if init.relative_filepath.is_absolute() -%}
+ {{ init.relative_package_filepath }}
+ {%- else -%}
+ {{ init.relative_filepath }}
+ {%- endif -%}
+
+ {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
+
+ Source code in
+ {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
+
+ {% endif %}
+ {% endif %}
+ {% endblock source %}
+
+ {% block children scoped %}
+ {#- Children block.
+
+ This block renders the children (members) of the class.
+ -#}
+ {% set root = False %}
+ {% set heading_level = heading_level + 1 %}
+ {% include "children.html.jinja" with context %}
+ {% endblock children %}
+ {% endblock contents %}
+ Source code in
+ {%- if class.relative_filepath.is_absolute() -%}
+ {{ class.relative_package_filepath }}
+ {%- else -%}
+ {{ class.relative_filepath }}
+ {%- endif -%}
+
+ {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
+ | {{ section.title or lang.t("Attributes:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Other parameters:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Parameters:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Raises:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Receives:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Returns:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Warns:") }} | +
+
|
+
|---|
| {{ section.title or lang.t("Yields:") }} | +
+
|
+
|---|
| Exceptions: | -
-
|
-
|---|
| Keyword arguments: | -
-
|
-
|---|
| Parameters: | -
-
|
-
|---|
| Returns: | -
-
|
-
|---|
| Yields: | -
-
|
-
|---|
+
+
+
diff --git a/tests/snapshots/headings/heading=,separate_signature=True.html b/tests/snapshots/headings/heading=,separate_signature=True.html
new file mode 100644
index 00000000..c73f0184
--- /dev/null
+++ b/tests/snapshots/headings/heading=,separate_signature=True.html
@@ -0,0 +1,18 @@
+
+
+
+
+ headings_package
+
+
+
+
+
+
+
+
diff --git a/tests/snapshots/headings/heading=Some heading,separate_signature=False.html b/tests/snapshots/headings/heading=Some heading,separate_signature=False.html
new file mode 100644
index 00000000..b000bf14
--- /dev/null
+++ b/tests/snapshots/headings/heading=Some heading,separate_signature=False.html
@@ -0,0 +1,16 @@
+
+
++ + headings_package + +
+
+
+
+
+
+
diff --git a/tests/snapshots/headings/heading=Some heading,separate_signature=True.html b/tests/snapshots/headings/heading=Some heading,separate_signature=True.html
new file mode 100644
index 00000000..852b7487
--- /dev/null
+++ b/tests/snapshots/headings/heading=Some heading,separate_signature=True.html
@@ -0,0 +1,16 @@
+
+
++ Some heading +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=('module_attribute',).html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=('module_attribute',).html
new file mode 100644
index 00000000..271501b7
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=('module_attribute',).html
@@ -0,0 +1,59 @@
+
+
++ Some heading +
+
+
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=().html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=().html
new file mode 100644
index 00000000..52ada349
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=().html
@@ -0,0 +1,26 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=False.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=False.html
new file mode 100644
index 00000000..e96d72c3
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=False.html
@@ -0,0 +1,26 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=None.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=None.html
new file mode 100644
index 00000000..dce4e148
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=None.html
@@ -0,0 +1,324 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=True.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=True.html
new file mode 100644
index 00000000..6d460dd2
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=('method1',),members=True.html
@@ -0,0 +1,355 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=('module_attribute',).html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=('module_attribute',).html
new file mode 100644
index 00000000..93503606
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=().html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=().html
new file mode 100644
index 00000000..fb55bdd1
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=False.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=False.html
new file mode 100644
index 00000000..3ae3af4d
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=None.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=None.html
new file mode 100644
index 00000000..793f43a4
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=None.html
@@ -0,0 +1,289 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=True.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=True.html
new file mode 100644
index 00000000..07120341
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=(),members=True.html
@@ -0,0 +1,320 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=('module_attribute',).html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=('module_attribute',).html
new file mode 100644
index 00000000..c27a4c82
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=().html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=().html
new file mode 100644
index 00000000..ec61d8e3
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=False.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=False.html
new file mode 100644
index 00000000..53b5e455
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=None.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=None.html
new file mode 100644
index 00000000..5a87832a
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=None.html
@@ -0,0 +1,289 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=True.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=True.html
new file mode 100644
index 00000000..40ebfa36
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=False,members=True.html
@@ -0,0 +1,320 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=('module_attribute',).html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=('module_attribute',).html
new file mode 100644
index 00000000..9aa9c3c1
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=().html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=().html
new file mode 100644
index 00000000..06640b9d
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=False.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=False.html
new file mode 100644
index 00000000..1f45fb80
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=None.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=None.html
new file mode 100644
index 00000000..cb43eee6
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=None.html
@@ -0,0 +1,477 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=True.html b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=True.html
new file mode 100644
index 00000000..8357168e
--- /dev/null
+++ b/tests/snapshots/members/filters=('!module_attribute',),inherited_members=True,members=True.html
@@ -0,0 +1,508 @@
+
+
+
+
+ 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:
+
+
+
+ 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/members/filters=('module_attribute',),inherited_members=('method1',),members=('module_attribute',).html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=('module_attribute',).html
new file mode 100644
index 00000000..e908da32
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=('module_attribute',).html
@@ -0,0 +1,59 @@
+
+
+
+
+ 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:
+
+
+
+ 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/members/filters=('module_attribute',),inherited_members=('method1',),members=().html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=().html
new file mode 100644
index 00000000..d1e4f8bd
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=().html
@@ -0,0 +1,26 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=False.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=False.html
new file mode 100644
index 00000000..5fbd6650
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=False.html
@@ -0,0 +1,26 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=None.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=None.html
new file mode 100644
index 00000000..d543f794
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=None.html
@@ -0,0 +1,57 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=True.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=True.html
new file mode 100644
index 00000000..795378be
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=('method1',),members=True.html
@@ -0,0 +1,167 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=('module_attribute',).html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=('module_attribute',).html
new file mode 100644
index 00000000..79900273
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
+
+
+ Class
+
+
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+
+
+
+
+ Subclass
+
+
+
+
+
+ Bases:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=().html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=().html
new file mode 100644
index 00000000..a0685468
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=False.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=False.html
new file mode 100644
index 00000000..bed00768
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=None.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=None.html
new file mode 100644
index 00000000..79a5ff40
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=None.html
@@ -0,0 +1,55 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=True.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=True.html
new file mode 100644
index 00000000..a7eb7dce
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=(),members=True.html
@@ -0,0 +1,132 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=('module_attribute',).html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=('module_attribute',).html
new file mode 100644
index 00000000..8fd78409
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
+
+
+ Class
+
+
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+
+
+
+
+ Subclass
+
+
+
+
+
+ Bases:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=().html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=().html
new file mode 100644
index 00000000..23e66fd7
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=False.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=False.html
new file mode 100644
index 00000000..27fcc6c1
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=None.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=None.html
new file mode 100644
index 00000000..1a8842f9
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=None.html
@@ -0,0 +1,55 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=True.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=True.html
new file mode 100644
index 00000000..e196b599
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=False,members=True.html
@@ -0,0 +1,132 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=('module_attribute',).html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=('module_attribute',).html
new file mode 100644
index 00000000..eb755e52
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
+
+
+ Class
+
+
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+
+
+
+
+ Subclass
+
+
+
+
+
+ Bases:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=().html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=().html
new file mode 100644
index 00000000..f827f125
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=False.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=False.html
new file mode 100644
index 00000000..48c42b3d
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=None.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=None.html
new file mode 100644
index 00000000..eddcbb25
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=None.html
@@ -0,0 +1,55 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=True.html b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=True.html
new file mode 100644
index 00000000..26cb9e39
--- /dev/null
+++ b/tests/snapshots/members/filters=('module_attribute',),inherited_members=True,members=True.html
@@ -0,0 +1,132 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=('method1',),members=('module_attribute',).html b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=('module_attribute',).html
new file mode 100644
index 00000000..a6ee2831
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
+
+
+ Class
+
+
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+
+
+
+
+ Subclass
+
+
+
+
+
+ Bases:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=('method1',),members=().html b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=().html
new file mode 100644
index 00000000..3b41766d
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=('method1',),members=False.html b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=False.html
new file mode 100644
index 00000000..3933bd9d
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=('method1',),members=None.html b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=None.html
new file mode 100644
index 00000000..d9ae307d
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=None.html
@@ -0,0 +1,353 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=('method1',),members=True.html b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=True.html
new file mode 100644
index 00000000..a52964c3
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=('method1',),members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=(),members=('module_attribute',).html b/tests/snapshots/members/filters=(),inherited_members=(),members=('module_attribute',).html
new file mode 100644
index 00000000..1232ad5e
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=(),members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=(),members=().html b/tests/snapshots/members/filters=(),inherited_members=(),members=().html
new file mode 100644
index 00000000..46cd4aee
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=(),members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=(),members=False.html b/tests/snapshots/members/filters=(),inherited_members=(),members=False.html
new file mode 100644
index 00000000..b6a621d2
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=(),members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=(),members=None.html b/tests/snapshots/members/filters=(),inherited_members=(),members=None.html
new file mode 100644
index 00000000..9058ed13
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=(),members=None.html
@@ -0,0 +1,318 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=(),members=True.html b/tests/snapshots/members/filters=(),inherited_members=(),members=True.html
new file mode 100644
index 00000000..ccfa8d64
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=(),members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=False,members=('module_attribute',).html b/tests/snapshots/members/filters=(),inherited_members=False,members=('module_attribute',).html
new file mode 100644
index 00000000..f2597daf
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=False,members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=False,members=().html b/tests/snapshots/members/filters=(),inherited_members=False,members=().html
new file mode 100644
index 00000000..ff8087d4
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=False,members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=False,members=False.html b/tests/snapshots/members/filters=(),inherited_members=False,members=False.html
new file mode 100644
index 00000000..eb15c707
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=False,members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=False,members=None.html b/tests/snapshots/members/filters=(),inherited_members=False,members=None.html
new file mode 100644
index 00000000..7c90168c
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=False,members=None.html
@@ -0,0 +1,318 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=False,members=True.html b/tests/snapshots/members/filters=(),inherited_members=False,members=True.html
new file mode 100644
index 00000000..d6c51063
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=False,members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=True,members=('module_attribute',).html b/tests/snapshots/members/filters=(),inherited_members=True,members=('module_attribute',).html
new file mode 100644
index 00000000..0ee900fb
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=True,members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=True,members=().html b/tests/snapshots/members/filters=(),inherited_members=True,members=().html
new file mode 100644
index 00000000..26f0f5ef
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=True,members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=True,members=False.html b/tests/snapshots/members/filters=(),inherited_members=True,members=False.html
new file mode 100644
index 00000000..bbd48b9e
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=True,members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=True,members=None.html b/tests/snapshots/members/filters=(),inherited_members=True,members=None.html
new file mode 100644
index 00000000..b2490df7
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=True,members=None.html
@@ -0,0 +1,506 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=(),inherited_members=True,members=True.html b/tests/snapshots/members/filters=(),inherited_members=True,members=True.html
new file mode 100644
index 00000000..7c65c72b
--- /dev/null
+++ b/tests/snapshots/members/filters=(),inherited_members=True,members=True.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:
+
+
+
+ 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/members/filters=None,inherited_members=('method1',),members=('module_attribute',).html b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=('module_attribute',).html
new file mode 100644
index 00000000..8501bce2
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ 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:
+
+
+
+ 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/members/filters=None,inherited_members=('method1',),members=().html b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=().html
new file mode 100644
index 00000000..7d734fba
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=('method1',),members=False.html b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=False.html
new file mode 100644
index 00000000..8c035cc8
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=('method1',),members=None.html b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=None.html
new file mode 100644
index 00000000..ddce47f6
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=None.html
@@ -0,0 +1,353 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=('method1',),members=True.html b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=True.html
new file mode 100644
index 00000000..fa970eca
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=('method1',),members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=(),members=('module_attribute',).html b/tests/snapshots/members/filters=None,inherited_members=(),members=('module_attribute',).html
new file mode 100644
index 00000000..b194ddc9
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=(),members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=(),members=().html b/tests/snapshots/members/filters=None,inherited_members=(),members=().html
new file mode 100644
index 00000000..4be85a18
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=(),members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=(),members=False.html b/tests/snapshots/members/filters=None,inherited_members=(),members=False.html
new file mode 100644
index 00000000..2bfbdbf4
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=(),members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=(),members=None.html b/tests/snapshots/members/filters=None,inherited_members=(),members=None.html
new file mode 100644
index 00000000..91614cf0
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=(),members=None.html
@@ -0,0 +1,318 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=(),members=True.html b/tests/snapshots/members/filters=None,inherited_members=(),members=True.html
new file mode 100644
index 00000000..2d79edd5
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=(),members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=False,members=('module_attribute',).html b/tests/snapshots/members/filters=None,inherited_members=False,members=('module_attribute',).html
new file mode 100644
index 00000000..96cff9d7
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=False,members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=False,members=().html b/tests/snapshots/members/filters=None,inherited_members=False,members=().html
new file mode 100644
index 00000000..0ed1d57b
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=False,members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=False,members=False.html b/tests/snapshots/members/filters=None,inherited_members=False,members=False.html
new file mode 100644
index 00000000..ce4ee8a7
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=False,members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=False,members=None.html b/tests/snapshots/members/filters=None,inherited_members=False,members=None.html
new file mode 100644
index 00000000..332a5c53
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=False,members=None.html
@@ -0,0 +1,318 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=False,members=True.html b/tests/snapshots/members/filters=None,inherited_members=False,members=True.html
new file mode 100644
index 00000000..cce2be49
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=False,members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=True,members=('module_attribute',).html b/tests/snapshots/members/filters=None,inherited_members=True,members=('module_attribute',).html
new file mode 100644
index 00000000..aa4ebf15
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=True,members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=True,members=().html b/tests/snapshots/members/filters=None,inherited_members=True,members=().html
new file mode 100644
index 00000000..898bab70
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=True,members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=True,members=False.html b/tests/snapshots/members/filters=None,inherited_members=True,members=False.html
new file mode 100644
index 00000000..8b4491f3
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=True,members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=True,members=None.html b/tests/snapshots/members/filters=None,inherited_members=True,members=None.html
new file mode 100644
index 00000000..68c7d720
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=True,members=None.html
@@ -0,0 +1,506 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=None,inherited_members=True,members=True.html b/tests/snapshots/members/filters=None,inherited_members=True,members=True.html
new file mode 100644
index 00000000..e9f375b2
--- /dev/null
+++ b/tests/snapshots/members/filters=None,inherited_members=True,members=True.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:
+
+
+
+ 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/members/filters=public,inherited_members=('method1',),members=('module_attribute',).html b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=('module_attribute',).html
new file mode 100644
index 00000000..befa0078
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=('module_attribute',).html
@@ -0,0 +1,57 @@
+
+
+
+
+ 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:
+
+
+
+ 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/members/filters=public,inherited_members=('method1',),members=().html b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=().html
new file mode 100644
index 00000000..f7385cf9
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=().html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=('method1',),members=False.html b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=False.html
new file mode 100644
index 00000000..e649c2e7
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=False.html
@@ -0,0 +1,24 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=('method1',),members=None.html b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=None.html
new file mode 100644
index 00000000..5ca6f9fe
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=None.html
@@ -0,0 +1,353 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=('method1',),members=True.html b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=True.html
new file mode 100644
index 00000000..a191cb33
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=('method1',),members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=(),members=('module_attribute',).html b/tests/snapshots/members/filters=public,inherited_members=(),members=('module_attribute',).html
new file mode 100644
index 00000000..c8211de8
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=(),members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ method1
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.method1
+
+ .
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=(),members=().html b/tests/snapshots/members/filters=public,inherited_members=(),members=().html
new file mode 100644
index 00000000..ac0222f5
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=(),members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=(),members=False.html b/tests/snapshots/members/filters=public,inherited_members=(),members=False.html
new file mode 100644
index 00000000..6f76b142
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=(),members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=(),members=None.html b/tests/snapshots/members/filters=public,inherited_members=(),members=None.html
new file mode 100644
index 00000000..5540be65
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=(),members=None.html
@@ -0,0 +1,318 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=(),members=True.html b/tests/snapshots/members/filters=public,inherited_members=(),members=True.html
new file mode 100644
index 00000000..7d596388
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=(),members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=False,members=('module_attribute',).html b/tests/snapshots/members/filters=public,inherited_members=False,members=('module_attribute',).html
new file mode 100644
index 00000000..e40923d9
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=False,members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=False,members=().html b/tests/snapshots/members/filters=public,inherited_members=False,members=().html
new file mode 100644
index 00000000..e8d65a7e
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=False,members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=False,members=False.html b/tests/snapshots/members/filters=public,inherited_members=False,members=False.html
new file mode 100644
index 00000000..12da79f0
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=False,members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=False,members=None.html b/tests/snapshots/members/filters=public,inherited_members=False,members=None.html
new file mode 100644
index 00000000..39cf1b20
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=False,members=None.html
@@ -0,0 +1,318 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=False,members=True.html b/tests/snapshots/members/filters=public,inherited_members=False,members=True.html
new file mode 100644
index 00000000..1973e99b
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=False,members=True.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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=True,members=('module_attribute',).html b/tests/snapshots/members/filters=public,inherited_members=True,members=('module_attribute',).html
new file mode 100644
index 00000000..7b0e60a5
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=True,members=('module_attribute',).html
@@ -0,0 +1,55 @@
+
+
+
+
+ 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:
+
+
+
+ Docstring for
+
+ Subclass
+
+ .
+
+
+
+
+
+
+
+
+
+ module_function
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ module_function
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=True,members=().html b/tests/snapshots/members/filters=public,inherited_members=True,members=().html
new file mode 100644
index 00000000..e8f0258e
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=True,members=().html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
+
+
+
+ module_attribute
+
+
+ =
+
+
+ 42
+
+
+
+
+
+ module-attribute
+
+
+
+
+
+
+
+ Docstring for
+
+ module_attribute
+
+ .
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=True,members=False.html b/tests/snapshots/members/filters=public,inherited_members=True,members=False.html
new file mode 100644
index 00000000..85cb268c
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=True,members=False.html
@@ -0,0 +1,22 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=True,members=None.html b/tests/snapshots/members/filters=public,inherited_members=True,members=None.html
new file mode 100644
index 00000000..40c14a7b
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=True,members=None.html
@@ -0,0 +1,506 @@
+
+
+
+
+ members_package
+
+
+
+
++ Docstring for the package. +
+
+
+
+
+
+
diff --git a/tests/snapshots/members/filters=public,inherited_members=True,members=True.html b/tests/snapshots/members/filters=public,inherited_members=True,members=True.html
new file mode 100644
index 00000000..13b2239c
--- /dev/null
+++ b/tests/snapshots/members/filters=public,inherited_members=True,members=True.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:
+
+
+
+ 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/overloads/overloads_only=False,separate_signature=False,show_overloads=False.html b/tests/snapshots/overloads/overloads_only=False,separate_signature=False,show_overloads=False.html
new file mode 100644
index 00000000..76234631
--- /dev/null
+++ b/tests/snapshots/overloads/overloads_only=False,separate_signature=False,show_overloads=False.html
@@ -0,0 +1,169 @@
+
+
+
+
+ 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:
+
+
+
+ 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/overloads/overloads_only=False,separate_signature=False,show_overloads=True.html b/tests/snapshots/overloads/overloads_only=False,separate_signature=False,show_overloads=True.html
new file mode 100644
index 00000000..afa94fae
--- /dev/null
+++ b/tests/snapshots/overloads/overloads_only=False,separate_signature=False,show_overloads=True.html
@@ -0,0 +1,189 @@
+
+
+
+
+ overloads_package
+
+
+
+
+
+
+
+
+
+
+
+
+ Class
+
+
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+
+
+
+
+
+ bar
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.bar
+
+ .
+
+
+
+
+
+
+
+ foo
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.foo
+
+ .
+
+
+
+
+
+
+
+ bar
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ bar
+
+ .
+
+
+
+
+
+
+
+ foo
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ foo
+
+ .
+
+
+
+
diff --git a/tests/snapshots/overloads/overloads_only=False,separate_signature=True,show_overloads=False.html b/tests/snapshots/overloads/overloads_only=False,separate_signature=True,show_overloads=False.html
new file mode 100644
index 00000000..96629ba3
--- /dev/null
+++ b/tests/snapshots/overloads/overloads_only=False,separate_signature=True,show_overloads=False.html
@@ -0,0 +1,117 @@
+
+
+
+
+ overloads_package
+
+
+
+
+
+
+
+
+
+
+
+
+ Class
+
+
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+
+
+
+
+
+ bar
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.bar
+
+ .
+
+
+
+
+
+
+
+ foo
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+
+ foo(a: int, b: str) -> float
+
+
+ foo(a: str, b: int) -> None
+
+
+
+ Docstring for
+
+ Class.foo
+
+ .
+
+
+
+
+
+
+
+ bar
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ bar
+
+ .
+
+
+
+
+
+
+
+ foo
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+
+ foo(a: int, b: str) -> float
+
+
+ foo(a: str, b: int) -> None
+
+
+
+ Docstring for
+
+ foo
+
+ .
+
+
diff --git a/tests/snapshots/overloads/overloads_only=False,separate_signature=True,show_overloads=True.html b/tests/snapshots/overloads/overloads_only=False,separate_signature=True,show_overloads=True.html
new file mode 100644
index 00000000..3f231581
--- /dev/null
+++ b/tests/snapshots/overloads/overloads_only=False,separate_signature=True,show_overloads=True.html
@@ -0,0 +1,137 @@
+
+
++ + overloads_package + +
+
+
+
+
+
+
+ + + Class + +
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+ + + bar + +
+
+
+ bar(a, b)
+
+
+
+ Docstring for
+
+ Class.bar
+
+ .
+
+
+ + + foo + +
+
+
+ foo(a, b)
+
+
+
+ Docstring for
+
+ Class.foo
+
+ .
+
+
+ + + bar + +
+
+
+ bar(a, b)
+
+
+
+ Docstring for
+
+ bar
+
+ .
+
+
+ + + foo + +
+
+
+ foo(a, b)
+
+
+
+ Docstring for
+
+ foo
+
+ .
+
+
diff --git a/tests/snapshots/overloads/overloads_only=True,separate_signature=False,show_overloads=False.html b/tests/snapshots/overloads/overloads_only=True,separate_signature=False,show_overloads=False.html
new file mode 100644
index 00000000..23a1a9c5
--- /dev/null
+++ b/tests/snapshots/overloads/overloads_only=True,separate_signature=False,show_overloads=False.html
@@ -0,0 +1,169 @@
+
+
++ + overloads_package + +
+
+
+
+
+
+
+ + + Class + +
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+ + + bar + +
+
+
+ bar(a, b)
+
+
+
+ Docstring for
+
+ Class.bar
+
+ .
+
+
+ + + foo + +
+
+
+
+
+ foo(a: int, b: str) -> float
+
+
+ foo(a: str, b: int) -> None
+
+
+ foo(a, b)
+
+
+
+ Docstring for
+
+ Class.foo
+
+ .
+
+
+ + + bar + +
+
+
+ bar(a, b)
+
+
+
+ Docstring for
+
+ bar
+
+ .
+
+
+ + + foo + +
+
+
+
+
+ foo(a: int, b: str) -> float
+
+
+ foo(a: str, b: int) -> None
+
+
+ foo(a, b)
+
+
+
+ Docstring for
+
+ foo
+
+ .
+
+
+
+
diff --git a/tests/snapshots/overloads/overloads_only=True,separate_signature=False,show_overloads=True.html b/tests/snapshots/overloads/overloads_only=True,separate_signature=False,show_overloads=True.html
new file mode 100644
index 00000000..79b078af
--- /dev/null
+++ b/tests/snapshots/overloads/overloads_only=True,separate_signature=False,show_overloads=True.html
@@ -0,0 +1,189 @@
+
+
+
+
+ overloads_package
+
+
+
+
+
+
+
+
+
+
+
+
+ Class
+
+
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+
+
+
+
+
+ bar
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.bar
+
+ .
+
+
+
+
+
+
+
+ foo
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.foo
+
+ .
+
+
+
+
+
+
+
+ bar
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ bar
+
+ .
+
+
+
+
+
+
+
+ foo
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ foo
+
+ .
+
+
+
+
diff --git a/tests/snapshots/overloads/overloads_only=True,separate_signature=True,show_overloads=False.html b/tests/snapshots/overloads/overloads_only=True,separate_signature=True,show_overloads=False.html
new file mode 100644
index 00000000..1f1c5822
--- /dev/null
+++ b/tests/snapshots/overloads/overloads_only=True,separate_signature=True,show_overloads=False.html
@@ -0,0 +1,117 @@
+
+
+
+
+ overloads_package
+
+
+
+
+
+
+
+
+
+
+
+
+ Class
+
+
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+
+
+
+
+
+ bar
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ Class.bar
+
+ .
+
+
+
+
+
+
+
+ foo
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+
+ foo(a: int, b: str) -> float
+
+
+ foo(a: str, b: int) -> None
+
+
+
+ Docstring for
+
+ Class.foo
+
+ .
+
+
+
+
+
+
+
+ bar
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+ Docstring for
+
+ bar
+
+ .
+
+
+
+
+
+
+
+ foo
+
+
+ (
+
+
+ a
+
+
+ ,
+
+
+ b
+
+
+ )
+
+
+
+
+
+
+
+ foo(a: int, b: str) -> float
+
+
+ foo(a: str, b: int) -> None
+
+
+
+ Docstring for
+
+ foo
+
+ .
+
+
diff --git a/tests/snapshots/overloads/overloads_only=True,separate_signature=True,show_overloads=True.html b/tests/snapshots/overloads/overloads_only=True,separate_signature=True,show_overloads=True.html
new file mode 100644
index 00000000..7d4b3416
--- /dev/null
+++ b/tests/snapshots/overloads/overloads_only=True,separate_signature=True,show_overloads=True.html
@@ -0,0 +1,129 @@
+
+
++ + overloads_package + +
+
+
+
+
+
+
+ + + Class + +
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+ + + bar + +
+
+
+ bar(a, b)
+
+
+
+ Docstring for
+
+ Class.bar
+
+ .
+
+
+ + + foo + +
+
+
+ foo(a, b)
+
+
+
+ Docstring for
+
+ Class.foo
+
+ .
+
+
+ + + bar + +
+
+
+ bar(a, b)
+
+
+
+ Docstring for
+
+ bar
+
+ .
+
+
+ + + foo + +
+
+
+ foo(a, b)
+
+
+
+ Docstring for
+
+ foo
+
+ .
+
+
diff --git a/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=False,signature_crossrefs=False.html b/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=False,signature_crossrefs=False.html
new file mode 100644
index 00000000..599197fe
--- /dev/null
+++ b/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=False,signature_crossrefs=False.html
@@ -0,0 +1,136 @@
+
+
++ + overloads_package + +
+
+
+
+
+
+
+ + + Class + +
+
+
+
+ Docstring for
+
+ Class
+
+ .
+
+
+
+
+ + + bar + +
+
+
+ bar(a, b)
+
+
+
+ Docstring for
+
+ Class.bar
+
+ .
+
+
+ + + foo + +
+
+
+
+
+ foo(a: int, b: str) -> float
+
+
+ foo(a: str, b: int) -> None
+
+
+
+ Docstring for
+
+ Class.foo
+
+ .
+
+
+ + + bar + +
+
+
+ bar(a, b)
+
+
+
+ Docstring for
+
+ bar
+
+ .
+
+
+ + + foo + +
+
+
+
+
+ foo(a: int, b: str) -> float
+
+
+ foo(a: str, b: int) -> None
+
+
+
+ Docstring for
+
+ foo
+
+ .
+
+
+
+
diff --git a/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=False,signature_crossrefs=True.html b/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=False,signature_crossrefs=True.html
new file mode 100644
index 00000000..70567c97
--- /dev/null
+++ b/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=False,signature_crossrefs=True.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/signatures/separate_signature=False,show_signature_annotations=True,signature_crossrefs=False.html b/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=True,signature_crossrefs=False.html
new file mode 100644
index 00000000..65e87e01
--- /dev/null
+++ b/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=True,signature_crossrefs=False.html
@@ -0,0 +1,190 @@
+
+
+
+
+ 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/signatures/separate_signature=False,show_signature_annotations=True,signature_crossrefs=True.html b/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=True,signature_crossrefs=True.html
new file mode 100644
index 00000000..44516fe5
--- /dev/null
+++ b/tests/snapshots/signatures/separate_signature=False,show_signature_annotations=True,signature_crossrefs=True.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/signatures/separate_signature=True,show_signature_annotations=False,signature_crossrefs=False.html b/tests/snapshots/signatures/separate_signature=True,show_signature_annotations=False,signature_crossrefs=False.html
new file mode 100644
index 00000000..03d9e14d
--- /dev/null
+++ b/tests/snapshots/signatures/separate_signature=True,show_signature_annotations=False,signature_crossrefs=False.html
@@ -0,0 +1,97 @@
+
+
+
+
+ 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/signatures/separate_signature=True,show_signature_annotations=False,signature_crossrefs=True.html b/tests/snapshots/signatures/separate_signature=True,show_signature_annotations=False,signature_crossrefs=True.html
new file mode 100644
index 00000000..8454da6d
--- /dev/null
+++ b/tests/snapshots/signatures/separate_signature=True,show_signature_annotations=False,signature_crossrefs=True.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/signatures/separate_signature=True,show_signature_annotations=True,signature_crossrefs=False.html b/tests/snapshots/signatures/separate_signature=True,show_signature_annotations=True,signature_crossrefs=False.html
new file mode 100644
index 00000000..9edcf4c5
--- /dev/null
+++ b/tests/snapshots/signatures/separate_signature=True,show_signature_annotations=True,signature_crossrefs=False.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/signatures/separate_signature=True,show_signature_annotations=True,signature_crossrefs=True.html b/tests/snapshots/signatures/separate_signature=True,show_signature_annotations=True,signature_crossrefs=True.html
new file mode 100644
index 00000000..e9ac18ce
--- /dev/null
+++ b/tests/snapshots/signatures/separate_signature=True,show_signature_annotations=True,signature_crossrefs=True.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/test_api.py b/tests/test_api.py
new file mode 100644
index 00000000..3322e2e6
--- /dev/null
+++ b/tests/test_api.py
@@ -0,0 +1,188 @@
+"""Tests for our own API exposition."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import griffe
+import pytest
+from mkdocstrings import Inventory
+
+from mkdocstrings_handlers import python
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+
+@pytest.fixture(name="loader", scope="module")
+def _fixture_loader() -> griffe.GriffeLoader:
+ loader = griffe.GriffeLoader()
+ loader.load("mkdocstrings")
+ loader.load("mkdocstrings_handlers.python")
+ loader.resolve_aliases()
+ return loader
+
+
+@pytest.fixture(name="internal_api", scope="module")
+def _fixture_internal_api(loader: griffe.GriffeLoader) -> griffe.Module:
+ return loader.modules_collection["mkdocstrings_handlers.python._internal"]
+
+
+@pytest.fixture(name="public_api", scope="module")
+def _fixture_public_api(loader: griffe.GriffeLoader) -> griffe.Module:
+ return loader.modules_collection["mkdocstrings_handlers.python"]
+
+
+def _yield_public_objects(
+ obj: griffe.Module | griffe.Class,
+ *,
+ modules: bool = False,
+ modulelevel: bool = True,
+ inherited: bool = False,
+ special: bool = False,
+) -> Iterator[griffe.Object | griffe.Alias]:
+ for member in obj.all_members.values() if inherited else obj.members.values():
+ try:
+ if member.is_module:
+ if member.is_alias or not member.is_public:
+ continue
+ if modules:
+ yield member
+ yield from _yield_public_objects(
+ member, # type: ignore[arg-type]
+ modules=modules,
+ modulelevel=modulelevel,
+ inherited=inherited,
+ special=special,
+ )
+ elif member.is_public and (special or not member.is_special):
+ yield member
+ else:
+ continue
+ if member.is_class and not modulelevel:
+ yield from _yield_public_objects(
+ member, # type: ignore[arg-type]
+ modules=modules,
+ modulelevel=False,
+ inherited=inherited,
+ special=special,
+ )
+ except (griffe.AliasResolutionError, griffe.CyclicAliasError):
+ continue
+
+
+@pytest.fixture(name="modulelevel_internal_objects", scope="module")
+def _fixture_modulelevel_internal_objects(internal_api: griffe.Module) -> list[griffe.Object | griffe.Alias]:
+ return list(_yield_public_objects(internal_api, modulelevel=True))
+
+
+@pytest.fixture(name="internal_objects", scope="module")
+def _fixture_internal_objects(internal_api: griffe.Module) -> list[griffe.Object | griffe.Alias]:
+ return list(_yield_public_objects(internal_api, modulelevel=False, special=True))
+
+
+@pytest.fixture(name="public_objects", scope="module")
+def _fixture_public_objects(public_api: griffe.Module) -> list[griffe.Object | griffe.Alias]:
+ return list(_yield_public_objects(public_api, modulelevel=False, inherited=True, special=True))
+
+
+@pytest.fixture(name="inventory", scope="module")
+def _fixture_inventory() -> Inventory:
+ inventory_file = Path(__file__).parent.parent / "site" / "objects.inv"
+ if not inventory_file.exists():
+ pytest.skip("The objects inventory is not available.") # ty: ignore[call-non-callable]
+ with inventory_file.open("rb") as file:
+ return Inventory.parse_sphinx(file)
+
+
+def test_exposed_objects(modulelevel_internal_objects: list[griffe.Object | griffe.Alias]) -> None:
+ """All public objects in the internal API are exposed under `mkdocstrings_handlers.python`."""
+ not_exposed = [
+ obj.path
+ for obj in modulelevel_internal_objects
+ if obj.name not in python.__all__ or not hasattr(python, obj.name)
+ ]
+ assert not not_exposed, "Objects not exposed:\n" + "\n".join(sorted(not_exposed))
+
+
+def test_unique_names(modulelevel_internal_objects: list[griffe.Object | griffe.Alias]) -> None:
+ """All internal objects have unique names."""
+ names_to_paths = defaultdict(list)
+ for obj in modulelevel_internal_objects:
+ names_to_paths[obj.name].append(obj.path)
+ non_unique = [paths for paths in names_to_paths.values() if len(paths) > 1]
+ assert not non_unique, "Non-unique names:\n" + "\n".join(str(paths) for paths in non_unique)
+
+
+def test_single_locations(public_api: griffe.Module) -> None:
+ """All objects have a single public location."""
+
+ def _public_path(obj: griffe.Object | griffe.Alias) -> bool:
+ return obj.is_public and (obj.parent is None or _public_path(obj.parent))
+
+ multiple_locations = {}
+ for obj_name in python.__all__:
+ obj = public_api[obj_name]
+ if obj.aliases and (
+ public_aliases := [path for path, alias in obj.aliases.items() if path != obj.path and _public_path(alias)]
+ ):
+ multiple_locations[obj.path] = public_aliases
+ assert not multiple_locations, "Multiple public locations:\n" + "\n".join(
+ f"{path}: {aliases}" for path, aliases in multiple_locations.items()
+ )
+
+
+def test_api_matches_inventory(inventory: Inventory, public_objects: list[griffe.Object | griffe.Alias]) -> None:
+ """All public objects are added to the inventory."""
+ ignore_names = {"__getattr__", "__init__", "__repr__", "__str__", "__post_init__"}
+ not_in_inventory = [
+ f"{obj.relative_filepath}:{obj.lineno}: {obj.path}"
+ for obj in public_objects
+ if obj.name not in ignore_names and obj.path not in inventory
+ ]
+ msg = "Objects not in the inventory (try running `make run mkdocs build`):\n{paths}"
+ assert not not_in_inventory, msg.format(paths="\n".join(sorted(not_in_inventory)))
+
+
+def _module_or_child(parent: str, name: str) -> bool:
+ parents = [parent[:i] for i, char in enumerate(parent) if char == "."]
+ parents.append(parent)
+ return name in parents or name.startswith(parent + ".")
+
+
+def test_inventory_matches_api(
+ inventory: Inventory,
+ public_objects: list[griffe.Object | griffe.Alias],
+ loader: griffe.GriffeLoader,
+) -> None:
+ """The inventory doesn't contain any additional Python object."""
+ not_in_api = []
+ public_api_paths = {obj.path for obj in public_objects}
+ public_api_paths.add("mkdocstrings_handlers")
+ public_api_paths.add("mkdocstrings_handlers.python")
+
+ for item in inventory.values():
+ if item.domain == "py" and "(" not in item.name and _module_or_child("mkdocstrings_handlers.python", item.name):
+ obj = loader.modules_collection[item.name]
+ if obj.path not in public_api_paths and not any(path in public_api_paths for path in obj.aliases):
+ not_in_api.append(item.name)
+ msg = "Inventory objects not in public API (try running `make run mkdocs build`):\n{paths}"
+ assert not not_in_api, msg.format(paths="\n".join(sorted(not_in_api)))
+
+
+def test_no_module_docstrings_in_internal_api(internal_api: griffe.Module) -> None:
+ """No module docstrings should be written in our internal API.
+
+ The reasoning is that docstrings are addressed to users of the public API,
+ but internal modules are not exposed to users, so they should not have docstrings.
+ """
+
+ def _modules(obj: griffe.Module) -> Iterator[griffe.Module]:
+ for member in obj.modules.values():
+ yield member
+ yield from _modules(member)
+
+ for obj in _modules(internal_api):
+ assert not obj.docstring
diff --git a/tests/test_end_to_end.py b/tests/test_end_to_end.py
new file mode 100644
index 00000000..3363ebd6
--- /dev/null
+++ b/tests/test_end_to_end.py
@@ -0,0 +1,283 @@
+"""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 external_file, register_format_alias
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+ from mkdocstrings_handlers.python import PythonHandler
+
+
+register_format_alias(".html", ".txt")
+
+
+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)
+
+ options = handler.get_options(handler_options)
+
+ handler._paths = [str(package.tmpdir)]
+ try:
+ data = handler.collect(package.name, 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, options)
+ return _normalize_html(html)
+
+
+def _render_options(options: dict[str, Any]) -> str:
+ return f"\n\n"
+
+
+def _snapshot_file(group: str, options: dict[str, Any]) -> str:
+ return f"snapshots/{group}/" + ",".join(f"{k}={v}" for k, v in sorted(options.items())) + ".html"
+
+
+# Signature tests.
+@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`.'''
+
+ def _private_function(a: int, b: str) -> None:
+ '''Docstring for `_private_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).
+ """
+ options = {
+ "show_signature_annotations": show_signature_annotations,
+ "signature_crossrefs": signature_crossrefs,
+ "separate_signature": separate_signature,
+ }
+ html = _render_options(options) + _render(session_handler, signature_package, options)
+ assert html == external_file(_snapshot_file("signatures", options), format=".txt")
+
+
+# Signature overloads tests.
+@pytest.fixture(name="overloads_package", scope="session")
+def _overloads_package() -> Iterator[TmpPackage]:
+ code = """
+ from typing_extensions import overload
+
+ @overload
+ def foo(a: int, b: str) -> float: ...
+
+ @overload
+ def foo(a: str, b: int) -> None: ...
+
+ def foo(a: str | int, b: int | str) -> float | None:
+ '''Docstring for `foo`.'''
+
+ def bar(a: str, b: int | str) -> float | None:
+ '''Docstring for `bar`.'''
+
+ class Class:
+ '''Docstring for `Class`.'''
+
+ @overload
+ def foo(self, a: int, b: str) -> float: ...
+
+ @overload
+ def foo(self, a: str, b: int) -> None: ...
+
+ def foo(self, a: str | int, b: int | str) -> float | None:
+ '''Docstring for `Class.foo`.'''
+
+ def bar(self, a: str, b: int | str) -> float | None:
+ '''Docstring for `Class.bar`.'''
+ """
+ with temporary_pypackage("overloads_package", {"__init__.py": code}) as tmppkg:
+ yield tmppkg
+
+
+@pytest.mark.parametrize("separate_signature", [True, False])
+@pytest.mark.parametrize("show_overloads", [True, False])
+@pytest.mark.parametrize("overloads_only", [True, False])
+def test_end_to_end_for_overloads(
+ session_handler: PythonHandler,
+ overloads_package: TmpPackage,
+ separate_signature: bool,
+ show_overloads: bool,
+ overloads_only: bool,
+) -> None:
+ """Test rendering of a given theme's templates.
+
+ Parameters:
+ identifier: Parametrized identifier.
+ session_handler: Python handler (fixture).
+ """
+ options = {
+ "separate_signature": separate_signature,
+ "show_overloads": show_overloads,
+ "overloads_only": overloads_only,
+ }
+ html = _render_options(options) + _render(session_handler, overloads_package, options)
+ assert html == external_file(_snapshot_file("overloads", options), format=".txt")
+
+
+# Member tests.
+@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",), "public", 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).
+ """
+ options = {
+ "inherited_members": inherited_members,
+ "members": members,
+ "filters": filters,
+ }
+ html = _render_options(options) + _render(session_handler, members_package, options)
+ assert html == external_file(_snapshot_file("members", options), format=".txt")
+
+
+# Heading tests.
+@pytest.fixture(name="headings_package", scope="session")
+def _headings_package() -> Iterator[TmpPackage]:
+ code = """
+ def module_function(a: int, b: str) -> None:
+ pass
+
+ class Class:
+ class_attribute: int = 42
+
+ def __init__(self, a: int, b: str) -> None:
+ self.instance_attribute = a + b
+
+ def method1(self, a: int, b: str) -> None:
+ pass
+
+ module_attribute: int = 42
+ """
+ with temporary_pypackage("headings_package", {"__init__.py": code}) as tmppkg:
+ yield tmppkg
+
+
+@pytest.mark.parametrize("separate_signature", [True, False])
+@pytest.mark.parametrize("heading", ["", "Some heading"])
+def test_end_to_end_for_headings(
+ session_handler: PythonHandler,
+ headings_package: TmpPackage,
+ separate_signature: bool,
+ heading: str,
+) -> None:
+ """Test rendering of a given theme's templates.
+
+ Parameters:
+ identifier: Parametrized identifier.
+ session_handler: Python handler (fixture).
+ """
+ options = {
+ "separate_signature": separate_signature,
+ "heading": heading,
+ }
+ extra = {"show_if_no_docstring": True, "members": False}
+ html = _render_options(options) + _render(session_handler, headings_package, {**options, **extra})
+ assert html == external_file(_snapshot_file("headings", options), format=".txt")
diff --git a/tests/test_handler.py b/tests/test_handler.py
index 5a49a8b1..1cccd6c6 100644
--- a/tests/test_handler.py
+++ b/tests/test_handler.py
@@ -1,35 +1,54 @@
"""Tests for the `handler` module."""
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import replace
+from glob import glob
+from io import BytesIO
+from pathlib import Path
+from textwrap import dedent
+from typing import TYPE_CHECKING
+
+import mkdocstrings
import pytest
-from griffe.docstrings.dataclasses import DocstringSectionExamples, DocstringSectionKind
+from griffe import (
+ Docstring,
+ DocstringSectionExamples,
+ DocstringSectionKind,
+ Module,
+ temporary_inspected_module,
+ temporary_visited_module,
+)
+from mkdocstrings import CollectionError
-from mkdocstrings_handlers.python.handler import CollectionError, get_handler
+from mkdocstrings_handlers.python import Inventory, PythonConfig, PythonHandler, PythonOptions
+if TYPE_CHECKING:
+ from mkdocstrings import MkdocstringsPlugin
-def test_collect_missing_module():
+
+def test_collect_missing_module(handler: PythonHandler) -> None:
"""Assert error is raised for missing modules."""
- handler = get_handler(theme="material")
with pytest.raises(CollectionError):
- handler.collect("aaaaaaaa", {})
+ handler.collect("aaaaaaaa", PythonOptions())
-def test_collect_missing_module_item():
+def test_collect_missing_module_item(handler: PythonHandler) -> None:
"""Assert error is raised for missing items within existing modules."""
- handler = get_handler(theme="material")
with pytest.raises(CollectionError):
- handler.collect("mkdocstrings.aaaaaaaa", {})
+ handler.collect("mkdocstrings.aaaaaaaa", PythonOptions())
-def test_collect_module():
+def test_collect_module(handler: PythonHandler) -> None:
"""Assert existing module can be collected."""
- handler = get_handler(theme="material")
- assert handler.collect("mkdocstrings", {})
+ assert handler.collect("mkdocstrings", PythonOptions())
-def test_collect_with_null_parser():
+def test_collect_with_null_parser(handler: PythonHandler) -> None:
"""Assert we can pass `None` as parser when collecting."""
- handler = get_handler(theme="material")
- assert handler.collect("mkdocstrings", {"docstring_style": None})
+ assert handler.collect("mkdocstrings", PythonOptions(docstring_style=None))
@pytest.mark.parametrize(
@@ -41,7 +60,7 @@ def test_collect_with_null_parser():
],
indirect=["handler"],
)
-def test_render_docstring_examples_section(handler):
+def test_render_docstring_examples_section(handler: PythonHandler) -> None:
"""Assert docstrings' examples section can be rendered.
Parameters:
@@ -53,8 +72,264 @@ def test_render_docstring_examples_section(handler):
(DocstringSectionKind.examples, ">>> print('Hello')\nHello"),
],
)
- template = handler.env.get_template("docstring/examples.html")
- rendered = template.render(section=section)
+ template = handler.env.get_template("docstring/examples.html.jinja")
+ rendered = template.render(section=section, locale="en")
+ template.render(section=section, locale="not_existing")
assert "+ + 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
+
+ .
+
This is an example.
" in rendered assert "print" in rendered assert "Hello" in rendered + + +def test_expand_globs(tmp_path: Path, plugin: MkdocstringsPlugin) -> None: + """Assert globs are correctly expanded. + + Parameters: + tmp_path: Pytext fixture that creates a temporary directory. + """ + globbed_names = ( + "expanded_a", + "expanded_b", + "other_expanded_c", + "other_expanded_d", + ) + globbed_paths = [tmp_path.joinpath(globbed_name) for globbed_name in globbed_names] + for path in globbed_paths: + path.touch() + plugin.handlers._tool_config.config_file_path = str(tmp_path.joinpath("mkdocs.yml")) + handler: PythonHandler = plugin.handlers.get_handler("python", {"paths": ["*exp*"]}) # type: ignore[assignment] + for path in globbed_paths: + assert str(path) in handler._paths + + +def test_expand_globs_without_changing_directory(plugin: MkdocstringsPlugin) -> None: + """Assert globs are correctly expanded when we are already in the right directory.""" + plugin.handlers._tool_config.config_file_path = "mkdocs.yml" + handler: PythonHandler = plugin.handlers.get_handler("python", {"paths": ["*.md"]}) # type: ignore[assignment] + for path in list(glob(os.path.abspath(".") + "/*.md")): + assert path in handler._paths + + +@pytest.mark.parametrize( + ("expect_change", "extension"), + [ + (True, "extension.py"), + (True, "extension.py:SomeExtension"), + (True, "path/to/extension.py"), + (True, "path/to/extension.py:SomeExtension"), + (True, {"extension.py": {"option": "value"}}), + (True, {"extension.py:SomeExtension": {"option": "value"}}), + (True, {"path/to/extension.py": {"option": "value"}}), + (True, {"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"}}), + (False, {"dot.notation.path.to.pyextension": {"option": "value"}}), + ], +) +def test_extension_paths( + tmp_path: Path, + expect_change: bool, + extension: str | dict, + plugin: MkdocstringsPlugin, +) -> None: + """Assert extension paths are resolved relative to config file.""" + plugin.handlers._tool_config.config_file_path = str(tmp_path.joinpath("mkdocs.yml")) + handler: PythonHandler = plugin.handlers.get_handler("python") # type: ignore[assignment] + normalized = handler.normalize_extension_paths([extension])[0] + if expect_change: + if isinstance(normalized, str) and isinstance(extension, str): + assert normalized == str(tmp_path.joinpath(extension)) + elif isinstance(normalized, dict) and isinstance(extension, dict): + pth, options = next(iter(extension.items())) + assert normalized == {str(tmp_path.joinpath(pth)): options} + else: + raise ValueError("Normalization must not change extension items type") + else: + assert normalized == extension + + +def test_rendering_object_source_without_lineno(handler: PythonHandler) -> None: + """Test rendering objects without a line number.""" + code = dedent( + """ + '''Module docstring.''' + + class Class: + '''Class docstring.''' + + def function(self): + '''Function docstring.''' + + attribute = 0 + '''Attribute docstring.''' + """, + ) + with temporary_visited_module(code) as module: + module["Class"].lineno = None + module["Class.function"].lineno = None + module["attribute"].lineno = None + assert handler.render(module, PythonOptions(show_source=True)) + + +def test_give_precedence_to_user_paths() -> None: + """Assert user paths take precedence over default paths.""" + last_sys_path = sys.path[-1] + handler = PythonHandler( + theme="material", + custom_templates=None, + base_dir=Path("."), + config=PythonConfig.from_data(paths=[last_sys_path]), + mdx=[], + mdx_config={}, + ) + assert handler._paths[0] == last_sys_path + + +@pytest.mark.parametrize( + ("section", "code"), + [ + ( + "Attributes", + """ + class A: + '''Summary. + + Attributes: + x: X. + y: Y. + ''' + x: int = 0 + '''X.''' + y: int = 0 + '''Y.''' + """, + ), + ( + "Methods", + """ + class A: + '''Summary. + + Methods: + x: X. + y: Y. + ''' + def x(self): ... + '''X.''' + def y(self): ... + '''Y.''' + """, + ), + ( + "Functions", + """ + '''Summary. + + Functions: + x: X. + y: Y. + ''' + def x(): ... + '''X.''' + def y(): ... + '''Y.''' + """, + ), + ( + "Classes", + """ + '''Summary. + + Classes: + A: A. + B: B. + ''' + class A: ... + '''A.''' + class B: ... + '''B.''' + """, + ), + ( + "Modules", + """ + '''Summary. + + Modules: + a: A. + b: B. + ''' + """, + ), + ], +) +def test_deduplicate_summary_sections(handler: PythonHandler, section: str, code: str) -> None: + """Assert summary sections are deduplicated.""" + summary_section = section.lower() + summary_section = "functions" if summary_section == "methods" else summary_section + with temporary_visited_module(code, docstring_parser="google") as module: + if summary_section == "modules": + module.set_member("a", Module("A", docstring=Docstring("A."))) + module.set_member("b", Module("B", docstring=Docstring("B."))) + html = handler.render( + module, + handler.get_options( + { + "summary": {summary_section: True}, + "show_source": False, + "show_submodules": True, + }, + ), + ) + assert html.count(f"{section}:") == 1 + + +def test_inheriting_self_from_parent_class(handler: PythonHandler) -> None: + """Inspect self only once when inheriting it from parent class.""" + with temporary_inspected_module( + """ + class A: ... + class B(A): ... + A.B = B + """, + ) as module: + # Assert no recusrion error. + handler.render( + module, + handler.get_options({"inherited_members": True}), + ) + + +def test_specifying_inventory_base_url(handler: PythonHandler) -> None: + """Assert that the handler renders inventory URLs using the specified base_url.""" + # Update handler config to include an inventory with a base URL + base_url = "https://docs.com/my_library" + inventory = Inventory(url="https://example.com/objects.inv", base_url=base_url) + handler.config = replace(handler.config, inventories=[inventory]) + + # Mock inventory bytes + item_name = "my_library.my_module.MyClass" + mocked_inventory = mkdocstrings.Inventory() + mocked_inventory.register( + name=item_name, + domain="py", + role="class", + uri=f"api-reference/#{item_name}", + dispname=item_name, + ) + mocked_bytes = BytesIO(mocked_inventory.format_sphinx()) + + # Get inventory URL and config + url, config = handler.get_inventory_urls()[0] + + # Load the mocked inventory + _, item_url = next(handler.load_inventory(mocked_bytes, url, **config)) + + # Assert the URL is based on the provided base URL + msg = "Expected inventory URL to start with base_url" + assert item_url.startswith(base_url), msg diff --git a/tests/test_rendering.py b/tests/test_rendering.py index 533eaf34..2616610f 100644 --- a/tests/test_rendering.py +++ b/tests/test_rendering.py @@ -1,24 +1,65 @@ """Tests for the `rendering` module.""" +from __future__ import annotations + import re from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Callable import pytest +from griffe import ModulesCollection, temporary_visited_module -from mkdocstrings_handlers.python import rendering +from mkdocstrings_handlers.python._internal import rendering +if TYPE_CHECKING: + from markupsafe import Markup -def test_format_code_and_signature(): - """Assert code and signatures can be Black-formatted.""" - assert rendering.do_format_code("print('Hello')", 100) - assert rendering.do_format_code('print("Hello")', 100) - assert rendering.do_format_signature("(param: str = 'hello') -> 'Class'", 100) - assert rendering.do_format_signature('(param: str = "hello") -> "Class"', 100) + +@pytest.mark.parametrize( + "code", + [ + "print('Hello')", + "aaaaa(bbbbb, ccccc=1) + ddddd.eeeee[ffff] or {ggggg: hhhhh, iiiii: jjjjj}", + ], +) +@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 formatter(code, length) + + +@pytest.mark.parametrize( + ("name", "signature"), + [("Class.method", "(param: str = 'hello') -> 'OtherClass'")], +) +def test_format_signature(name: Markup, signature: str) -> None: + """Assert signatures can be formatted. + + Parameters: + signature: Signature to format. + """ + for length in (5, 100): + assert rendering._format_signature(name, signature, length) @dataclass class _FakeObject: name: str + inherited: bool = False + parent: None = None + is_alias: bool = False @pytest.mark.parametrize( @@ -28,7 +69,7 @@ class _FakeObject: (["aa", "ab", "ac", "da"], {"members_list": ["aa", "ab"]}, {"aa", "ab"}), ], ) -def test_filter_objects(names, filter_params, expected_names): +def test_filter_objects(names: list[str], filter_params: dict[str, Any], expected_names: set[str]) -> None: """Assert the objects filter works correctly. Parameters: @@ -37,6 +78,99 @@ def test_filter_objects(names, filter_params, expected_names): expected_names: Names expected to be kept. """ objects = {name: _FakeObject(name) for name in names} - filtered = rendering.do_filter_objects(objects, **filter_params) + filtered = rendering.do_filter_objects(objects, **filter_params) # type: ignore[arg-type] filtered_names = {obj.name for obj in filtered} assert set(filtered_names) == set(expected_names) + + +@pytest.mark.parametrize( + ("members", "inherited_members", "expected_names"), + [ + (True, True, {"base", "main"}), + (True, False, {"main"}), + (True, ["base"], {"base", "main"}), + (True, [], {"main"}), + (False, True, {"base"}), + (False, False, set()), + (False, ["base"], {"base"}), + (False, [], set()), + ([], True, {"base"}), + ([], False, set()), + ([], ["base"], {"base"}), + ([], [], set()), + (None, True, {"base", "main"}), + (None, False, {"main"}), + (None, ["base"], {"base", "main"}), + (None, [], {"main"}), + (["base"], True, {"base"}), + (["base"], False, set()), + (["base"], ["base"], {"base"}), + (["base"], [], set()), + (["main"], True, {"main"}), + (["main"], False, {"main"}), + (["main"], ["base"], {"base", "main"}), + (["main"], [], {"main"}), + ], +) +def test_filter_inherited_members( + members: bool | list[str] | None, + inherited_members: bool | list[str], + expected_names: list[str], +) -> None: + """Test inherited members filtering. + + Parameters: + members: Members option (parametrized). + inherited_members: Inherited members option (parametrized). + expected_names: The expected result as a list of member names. + """ + collection = ModulesCollection() + with temporary_visited_module( + """ + class Base: + def base(self): ... + + class Main(Base): + def main(self): ... + """, + modules_collection=collection, + ) as module: + collection["module"] = module + objects = module["Main"].all_members + filtered = rendering.do_filter_objects(objects, members_list=members, inherited_members=inherited_members) + names = {obj.name for obj in filtered} + assert names == expected_names + + +@pytest.mark.parametrize( + ("order", "members_list", "expected_names"), + [ + ("alphabetical", None, ["a", "b", "c"]), + ("source", None, ["c", "b", "a"]), + ("alphabetical", ["c", "b"], ["c", "b"]), + ("source", ["a", "c"], ["a", "c"]), + ("alphabetical", [], ["a", "b", "c"]), + ("source", [], ["c", "b", "a"]), + ("alphabetical", True, ["a", "b", "c"]), + ("source", False, ["c", "b", "a"]), + ], +) +def test_ordering_members(order: rendering.Order, members_list: list[str | None], expected_names: list[str]) -> None: + """Assert the objects are correctly ordered. + + Parameters: + order: The order to use (alphabetical or source). + members_list: The user specified members list. + expected_names: The expected ordered list of object names. + """ + + class Obj: + def __init__(self, name: str, lineno: int | None = None, *, is_alias: bool = False) -> None: + self.name = name + self.lineno = lineno + self.alias_lineno = lineno + self.is_alias = is_alias + + members = [Obj("a", 10, is_alias=True), Obj("b", 9, is_alias=False), Obj("c", 8, is_alias=True)] + ordered = rendering.do_order_members(members, order, members_list) # type: ignore[arg-type] + assert [obj.name for obj in ordered] == expected_names diff --git a/tests/test_themes.py b/tests/test_themes.py index b1e7d5d5..5a7e9038 100644 --- a/tests/test_themes.py +++ b/tests/test_themes.py @@ -1,9 +1,14 @@ """Tests for the different themes we claim to support.""" -import sys +from __future__ import annotations + +from typing import TYPE_CHECKING import pytest +if TYPE_CHECKING: + from mkdocstrings_handlers.python import PythonHandler + @pytest.mark.parametrize( "plugin", @@ -15,26 +20,20 @@ indirect=["plugin"], ) @pytest.mark.parametrize( - "module", + "identifier", [ - "mkdocstrings.extension", - "mkdocstrings.inventory", - "mkdocstrings.loggers", - "mkdocstrings.plugin", - "mkdocstrings.handlers.base", - "mkdocstrings.handlers.rendering", - "mkdocstrings_handlers.python", + "mkdocstrings_handlers.python._internal.config", + "mkdocstrings_handlers.python._internal.handler", + "mkdocstrings_handlers.python._internal.rendering", ], ) -@pytest.mark.skipif(sys.version_info < (3, 7), reason="material is not installed on Python 3.6") -def test_render_themes_templates_python(module, plugin): +def test_render_themes_templates_python(identifier: str, handler: PythonHandler) -> None: """Test rendering of a given theme's templates. Parameters: - module: Parametrized argument. - plugin: Pytest fixture: [tests.conftest.fixture_plugin][]. + identifier: Parametrized identifier. + handler: Python handler (fixture). """ - handler = plugin.handlers.get_handler("python") - handler._update_env(plugin.md, plugin.handlers._config) # noqa: WPS437 - data = handler.collect(module, {}) - handler.render(data, {}) + options = handler.get_options({}) + data = handler.collect(identifier, options) + handler.render(data, options)