Summary.
+Functions:
+ +**Name** | **Description** +-------- | --------------- +`foo` | Some function. + +ClassSummary.
+Methods:
+ +**Name** | **Description** +-------- | --------------- +`bar` | Some method. +//// + +//// tab | Without functions +Summary.
+ClassSummary.
+//// +/// + + +## `show_docstring_classes` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Classes" sections 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 +Summary.
+Classes:
+ +**Name** | **Description** +-------- | --------------- +`Class` | Some class. + +ClassSummary.
+//// + +//// tab | Without classes +Summary.
+ClassSummary.
+//// +/// + +## `show_docstring_modules` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Modules" sections 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 +Summary.
+Modules:
+ +**Name** | **Description** +----------- | --------------- +`submodule` | Some module. + +//// + +//// tab | Without modules +Summary.
+//// +/// + ## `show_docstring_description` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index 921f9187..320d0074 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -125,7 +125,8 @@ plugins: type: quote ```python linenums="1" -def some_function(): ... +def some_function(): + ... ``` ///// //// diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md index 17ef9527..16c707d0 100644 --- a/docs/usage/configuration/members.md +++ b/docs/usage/configuration/members.md @@ -47,14 +47,18 @@ plugins: ```python title="package/module.py" """Module docstring.""" + def this_function(): """Function docstring.""" + class ThisClass: """Class docstring.""" + def method(self): """Method docstring.""" + this_attribute = 0 """Attribute docstring.""" ``` @@ -207,6 +211,7 @@ plugins: ```python title="package/module.py" """Module docstring.""" + class Base: """Base class.""" @@ -283,12 +288,15 @@ plugins: ```python title="package/module.py" """Module docstring.""" + def function_b(): """Function a.""" + def function_a(): """Function b.""" + def function_c(): """Function c.""" ``` @@ -373,8 +381,12 @@ plugins: ``` ```python title="package/module.py" -def hello(): ... -def _world(): ... +def hello(): + ... + + +def _world(): + ... ``` /// admonition | Preview @@ -437,10 +449,19 @@ plugins: ``` ```python title="package/module.py" -def function_a(): ... -class ClassB: ... +def function_a(): + ... + + +class ClassB: + ... + + attribute_C = 0 -def function_d(): ... + + +def function_d(): + ... ``` /// admonition | Preview diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 0dd5397f..7bbed955 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -63,7 +63,11 @@ 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 "")) + 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/master/src/mkdocstrings_handlers/python/templates/). @@ -151,7 +155,17 @@ Available context: #### Docstring sections -In `docstring/attributes.html`, `docstring/other_parameters.html`, `docstring/parameters.html`, `docstring/raises.html`, `docstring/receives.html`, `docstring/returns.html`, `docstring/warns.html`, and `docstring/yields.html`: +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/warns.html`, +and `docstring/yields.html`: - `table_style`: The section as a table. - `list_style`: The section as a list. diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index bd25424d..5fe76682 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -84,6 +84,9 @@ class PythonHandler(BaseHandler): "line_length": 60, "merge_init_into_class": False, "show_docstring_attributes": True, + "show_docstring_functions": True, + "show_docstring_classes": True, + "show_docstring_modules": True, "show_docstring_description": True, "show_docstring_examples": True, "show_docstring_other_parameters": True, @@ -157,6 +160,9 @@ class PythonHandler(BaseHandler): merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`. show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`. show_docstring_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`. + show_docstring_functions (bool): Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: `True`. + show_docstring_classes (bool): Whether to display the "Classes" section in the object's docstring. Default: `True`. + show_docstring_modules (bool): Whether to display the "Modules" section in the object's docstring. Default: `True`. show_docstring_description (bool): Whether to display the textual block (including admonitions) in the object's docstring. Default: `True`. show_docstring_examples (bool): Whether to display the "Examples" section in the object's docstring. Default: `True`. show_docstring_other_parameters (bool): Whether to display the "Other Parameters" section in the object's docstring. Default: `True`. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html index 42fd4824..1d416a3b 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html @@ -1,7 +1,7 @@ {{ log.debug("Rendering " + attribute.path) }}{{ section.title or lang.t("Classes:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
{{ class.name }} |
+
+
+ {{ class.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Classes:") }}
+| {{ (section.title or lang.t("CLASS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
{{ class.name }} |
+
+
+ {{ class.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
{{ function.name }} |
+
+
+ {{ function.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Methods:") if obj.is_class else lang.t("Functions:") }}
+| {{ (section.title or lang.t("METHOD") if obj.is_class else lang.t("FUNCTION")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
{{ function.name }} |
+
+
+ {{ function.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Modules:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
{{ module.name }} |
+
+
+ {{ module.description|convert_markdown(heading_level, html_id) }}
+
+ |
+
{{ section.title or lang.t("Modules:") }}
+| {{ (section.title or lang.t("MODULE")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
{{ module.name }} |
+
+
+ {{ module.description|convert_markdown(heading_level, html_id) }}
+
+ |
+