diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 3c8ac843..ab70887a 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -2,6 +2,32 @@ ## mkdocstrings-python Insiders +### 1.8.3 June 19, 2024 { id="1.8.3" } + +- Update code for Griffe 0.46+ to avoid deprecation warnings + +### 1.8.2 May 09, 2024 { id="1.8.2" } + +- Don't render cross-refs for default values when signatures aren't separated + +### 1.8.1 April 19, 2024 { id="1.8.1" } + +- Render enumeration instance name instead of just "value", allowing proper cross-reference + +### 1.8.0 March 24, 2024 { id="1.8.0" } + +- [Annotations modernization][modernize_annotations] + +### 1.7.0 March 24, 2024 { id="1.7.0" } + +- [Class inheritance diagrams with Mermaid][show_inheritance_diagram] + +### 1.6.0 January 30, 2024 { id="1.6.0" } + +- Render cross-references to parameters documentation in signatures and attribute values. +- Add [`parameter_headings`][parameter_headings] option to render headings for parameters (enabling permalinks and ToC/inventory entries). +- Render cross-references for default parameter values in signatures. + ### 1.5.1 September 12, 2023 { id="1.5.1" } - Prevent empty auto-summarized Methods section. diff --git a/docs/insiders/goals.yml b/docs/insiders/goals.yml index 381e5029..57985eae 100644 --- a/docs/insiders/goals.yml +++ b/docs/insiders/goals.yml @@ -16,9 +16,24 @@ goals: since: 2023/08/20 - name: Automatic rendering of function signature overloads since: 2023/09/05 + - name: Parameter headings + ref: /usage/configuration/headings/#parameter_headings + since: 2024/01/30 + - name: Automatic cross-references to parameters + ref: /usage/configuration/headings/#parameter_headings + since: 2024/01/30 + - name: Automatic cross-references for default parameter values in signatures + since: 2024/01/30 1500: name: HyperLamp Navigation Tips - features: [] + features: + - name: Class inheritance diagrams with Mermaid + ref: /usage/configuration/general/#show_inheritance_diagram + since: 2024/03/24 + - name: Annotations modernization + ref: /usage/configuration/signatures/#modernize_annotations + since: 2024/03/24 2000: name: FusionDrive Ejection Configuration - features: [] + features: + - name: Relative cross-references 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/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/configuration/general.md b/docs/usage/configuration/general.md index d8d7f250..e2a6e169 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -92,6 +92,91 @@ plugins: //// /// +## `show_inheritance_diagram` + +[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — +[:octicons-tag-24: Insiders 1.7.0](../../insiders/changelog.md#1.7.0) + +- **: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.* +/// + ## `show_source` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index a9b75e6d..63950206 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -57,6 +57,129 @@ plugins: //// /// +## `parameter_headings` + +[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — +[:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0) + +- **: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. +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 + + get_version
+ dist + +To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types). + +/// + ## `show_root_heading` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index da96dc5b..e5e4cb88 100644 --- a/docs/usage/configuration/signatures.md +++ b/docs/usage/configuration/signatures.md @@ -193,6 +193,93 @@ plugins: //// /// +## `modernize_annotations` + +[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — +[:octicons-tag-24: Insiders 1.8.0](../../insiders/changelog.md#1.8.0) — +**This feature also requires +[Griffe Insiders](https://mkdocstrings.github.io/griffe/insiders/) +to be installed.** + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Modernize annotations with latest features and PEPs of the Python language. + +The Python language keeps evolving, and often library developers +must continue to support a few minor versions of Python. +Therefore they cannot use some features that were introduced +in the latest versions. + +Yet this doesn't mean they can't enjoy latest features in their docs: +Griffe allows to "modernize" expressions, for example +by replacing `typing.Union` with [PEP 604][pep-604] type unions `|`. +Thanks to this, mkdocstrings' Python handler +can automatically transform type annotations into their modern equivalent. +This improves consistency in your docs, and shows users +how to use your code with the latest features of the language. + +[pep-604]: https://peps.python.org/pep-0604/ + +Modernizations applied: + +- `typing.Dict[A, B]` becomes `dict[A, B]` +- `typing.List[A]` becomes `list[A]` +- `typing.Set[A]` becomes `set[A]` +- `typing.Tuple[A]` becomes `tuple[A]` +- `typing.Union[A, B]` becomes `A | B` +- `typing.Optional[A]` becomes `A | None` + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + modernize_annotations: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + modernize_annotations: false +``` + +/// admonition | Preview + type: preview + +```python +--8<-- "docs/snippets/package/modern.py" +``` + +//// tab | Unchanged annotations + +```md exec="on" +::: package.modern.example + options: + modernize_annotations: false + show_symbol_type_heading: false + show_labels: false +``` + +//// + +//// tab | Modernized annotations + +```md exec="on" +::: package.modern.example + options: + modernize_annotations: true + show_symbol_type_heading: false + show_labels: false +``` + +//// + +/// + + + ## `show_signature` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 5e82001e..907809c8 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -89,12 +89,14 @@ 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-attribute-fg-color: #0079ff; --doc-symbol-function-fg-color: #00dfa2; --doc-symbol-method-fg-color: #00dfa2; --doc-symbol-class-fg-color: #d1b619; --doc-symbol-module-fg-color: #ff0060; + --doc-symbol-parameter-bg-color: #df50af1a; --doc-symbol-attribute-bg-color: #0079ff1a; --doc-symbol-function-bg-color: #00dfa21a; --doc-symbol-method-bg-color: #00dfa21a; @@ -103,12 +105,14 @@ by overriding the values of our CSS variables, for example: } [data-md-color-scheme="slate"] { + --doc-symbol-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-module-fg-color: #f2f7a1; + --doc-symbol-parameter-bg-color: #ffa8cc1a; --doc-symbol-attribute-bg-color: #963fb81a; --doc-symbol-function-bg-color: #6d67e41a; --doc-symbol-method-bg-color: #6d67e41a; @@ -124,12 +128,14 @@ otherwise just override the variables at root level: ```css title="docs/css/mkdocstrings.css" :root { + --doc-symbol-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-module-fg-color: #ff0060; + --doc-symbol-parameter-bg-color: #df50af1a; --doc-symbol-attribute-bg-color: #0079ff1a; --doc-symbol-function-bg-color: #00dfa21a; --doc-symbol-method-bg-color: #00dfa21a; @@ -144,12 +150,14 @@ otherwise just override the variables at root level:

Try cycling through the themes to see the colors for each theme: + @@ -189,6 +200,10 @@ 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-attribute::after { content: "A"; } @@ -215,6 +230,10 @@ For example, to use single letters instead of truncated types: