Docstring of the method.
//// /// + +## `show_symbol_type_heading` + +[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0) + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Show the symbol type in headings. + +This option will prefix headings with +moduleDocstring of the module.
+attributeDocstring of the module attribute.
+functionDocstring of the function.
+ClassDocstring of the class.
+methodDocstring of the method.
+//// + +//// tab | Without symbol type in headings +moduleDocstring of the module.
+attributeDocstring of the module attribute.
+functionDocstring of the function.
+ClassDocstring of the class.
+methodDocstring of the method.
+//// +/// + +## `show_symbol_type_toc` + +[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0) + +- **: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 +subpackage_memberMember docstring.
//// -/// \ No newline at end of file +/// + +## `summary` + +[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — +[:octicons-tag-24: Insiders 1.2.0](../../insiders/changelog.md#1.2.0) + +- **:octicons-package-24: Typebool | dict[str, bool] :material-equal: `False`{ title="default value" }**
+
+
+Whether to render summaries of modules, classes, functions (methods) and attributes.
+
+This option accepts a boolean (`yes`, `true`, `no`, `false` in YAML)
+or a dictionary with one or more of the following keys: `attributes`, `functions`, `classes`, `modules`,
+with booleans as values. Class methods summary is (de)activated with the `functions` key.
+By default, `summary` is false, and by extension all values are false.
+
+Examples:
+
+```yaml
+summary: true
+```
+
+```yaml
+summary: false
+```
+
+```yaml
+summary:
+ attributes: false
+ functions: true
+ modules: false
+```
+
+Summaries will be rendered as the corresponding docstring sections.
+For example, the summary for attributes will be rendered as an Attributes docstring section.
+The section will be rendered in accordance with the [`docstring_section_style`][] option.
+If the objects appearing in the summary are also rendered on the page
+(or somewhere else on the site), their name will automatically link to their rendered documentation.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+ handlers:
+ python:
+ options:
+ summary: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+ options:
+ summary: false
+```
+
+/// admonition | Preview
+ type: preview
+
+//// tab | With all summaries
+```
+::: path.to.module.MyClass
+ options:
+ summary: true
+```
+Class docstring.
+Methods:
+Attributes:
+Class docstring.
+Methods:
+Function docstring.
+//// + +//// tab | Without signature cross-references +do_format_code(code: str, line_length: int) -> str
+Function docstring.
+//// +/// ## `unwrap_annotated` diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 7bbed955..9dedbf20 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -23,6 +23,10 @@ The following CSS classes are used in the generated HTML: - `doc-label`: on `small` elements containing a label - `doc-label-LABEL`: same, where `LABEL` is replaced by the actual label - `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`) /// admonition | Example with colorful labels type: example @@ -53,6 +57,173 @@ The following CSS classes are used in the generated HTML: /// +## 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-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-attribute-bg-color: #0079ff1a; + --doc-symbol-function-bg-color: #00dfa21a; + --doc-symbol-method-bg-color: #00dfa21a; + --doc-symbol-class-bg-color: #d1b6191a; + --doc-symbol-module-bg-color: #ff00601a; +} + +[data-md-color-scheme="slate"] { + --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-attribute-bg-color: #963fb81a; + --doc-symbol-function-bg-color: #6d67e41a; + --doc-symbol-method-bg-color: #6d67e41a; + --doc-symbol-class-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-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-attribute-bg-color: #0079ff1a; + --doc-symbol-function-bg-color: #00dfa21a; + --doc-symbol-method-bg-color: #00dfa21a; + --doc-symbol-class-bg-color: #d1b6191a; + --doc-symbol-module-bg-color: #ff00601a; +} +``` + +/// admonition | Preview + type: preview + +
+ Try cycling through the themes to see the colors for each theme:
+
+
+
+
+
+
{{ attribute.name }}{{ attribute.name }}{{ attribute.name }}
+ {{ attribute.name }}
{% if attribute.annotation %}
{% with expression = attribute.annotation %}
({% include "expression.html" with context %})
@@ -66,7 +66,7 @@
{% for attribute in section.value %}
{{ attribute.name }}{{ attribute.name }}{{ class.name }}{{ class.name }}{{ class.name }}
+ {{ class.name }}
–
{{ class.name }}{{ class.name }}{{ function.name }}{{ function.name }}{{ function.name }}
+ {{ function.name }}
–
{{ function.name }}{{ function.name }}{{ module.name }}{{ module.name }}{{ module.name }}
+ {{ module.name }}
–
{{ module.name }}{{ module.name }}