From 7b11ba86a6ca6a1e8ec5d720e0d167062b44a4a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 3 Sep 2024 19:13:38 +0200 Subject: [PATCH] docs: Update docs from insiders --- docs/insiders/changelog.md | 26 ++++++ docs/insiders/goals.yml | 19 +++- docs/snippets/package/__init__.py | 19 ++++ docs/snippets/package/modern.py | 3 + docs/usage/configuration/general.md | 85 +++++++++++++++++ docs/usage/configuration/headings.md | 123 +++++++++++++++++++++++++ docs/usage/configuration/signatures.md | 87 +++++++++++++++++ docs/usage/customization.md | 20 ++++ mkdocs.yml | 15 ++- 9 files changed, 391 insertions(+), 6 deletions(-) create mode 100644 docs/snippets/package/__init__.py create mode 100644 docs/snippets/package/modern.py diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 3c8ac84..ab70887 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 381e502..57985ea 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 0000000..b19123b --- /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 0000000..c992b5d --- /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 d8d7f25..e2a6e16 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 a9b75e6..6395020 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 da96dc5..e5e4cb8 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 5e82001..907809c 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:

    +
  • Parameter:
  • Attribute:
  • Function:
  • Method:
    • diff --git a/mkdocs.yml b/mkdocs.yml index 040ab89..19aa90d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -116,14 +116,16 @@ markdown_extensions: emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight: pygments_lang_class: true -- pymdownx.inlinehilite: - style_plain_text: py3 - pymdownx.magiclink - pymdownx.snippets: auto_append: [docs/.glossary.md] base_path: [!relative $config_dir] check_paths: true -- pymdownx.superfences +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true slugify: !!python/object/apply:pymdownx.slugs.slugify @@ -147,10 +149,11 @@ plugins: - mkdocstrings: handlers: python: - paths: [src] + paths: [src, docs/snippets] import: - https://docs.python.org/3/objects.inv - https://mkdocstrings.github.io/objects.inv + - https://mkdocstrings.github.io/autorefs/objects.inv - https://mkdocstrings.github.io/griffe/objects.inv - https://python-markdown.github.io/objects.inv options: @@ -163,7 +166,11 @@ plugins: merge_init_into_class: true parameter_headings: true preload_modules: [mkdocstrings] + relative_crossrefs: true + scoped_crossrefs: true separate_signature: true + show_bases: false + show_inheritance_diagram: true show_root_heading: true show_root_full_path: false show_signature_annotations: true