From d5337afdf68fc492b34f749aa69d1da33b49f9c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 20 Aug 2023 17:11:54 +0200 Subject: [PATCH 1/3] feat: Add support for new Griffe docstring sections: modules, classes, and functions (methods) --- docs/usage/configuration/docstrings.md | 189 ++++++++++++++++++ docs/usage/customization.md | 12 +- src/mkdocstrings_handlers/python/handler.py | 6 + .../templates/material/_base/attribute.html | 2 +- .../templates/material/_base/class.html | 2 +- .../templates/material/_base/docstring.html | 6 + .../material/_base/docstring/classes.html | 67 +++++++ .../material/_base/docstring/functions.html | 73 +++++++ .../material/_base/docstring/modules.html | 67 +++++++ .../templates/material/_base/function.html | 2 +- .../material/_base/languages/en.html | 62 +++--- .../material/_base/languages/ja.html | 8 + .../material/_base/languages/zh.html | 62 +++--- .../templates/material/_base/module.html | 2 +- .../templates/material/docstring/classes.html | 1 + .../material/docstring/functions.html | 1 + .../templates/material/docstring/modules.html | 1 + 17 files changed, 504 insertions(+), 59 deletions(-) create mode 100644 src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/docstring/classes.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/docstring/functions.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/docstring/modules.html diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md index 4e56b745..87944a09 100644 --- a/docs/usage/configuration/docstrings.md +++ b/docs/usage/configuration/docstrings.md @@ -449,6 +449,195 @@ class Class: //// /// +## `show_docstring_functions` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Whether to render the "Functions" or "Methods" sections 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.

+//// +/// + + +## `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 +

module

+

Summary.

+

Classes:

+ +**Name** | **Description** +-------- | --------------- +`Class` | Some class. + +

Class

+

Summary.

+//// + +//// tab | Without classes +

module

+

Summary.

+

Class

+

Summary.

+//// +/// + +## `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 +

module

+

Summary.

+

Modules:

+ +**Name** | **Description** +----------- | --------------- +`submodule` | Some module. + +//// + +//// tab | Without modules +

module

+

Summary.

+//// +/// + ## `show_docstring_description` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 0dd5397f..955420b6 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -151,7 +151,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) }}
-{% with html_id = attribute.path %} +{% with obj = attribute, html_id = attribute.path %} {% if root %} {% set show_full_path = config.show_root_full_path %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html b/src/mkdocstrings_handlers/python/templates/material/_base/class.html index e035d1f5..af019330 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html @@ -1,7 +1,7 @@ {{ log.debug("Rendering " + class.path) }}
-{% with html_id = class.path %} +{% with obj = class, html_id = class.path %} {% if root %} {% set show_full_path = config.show_root_full_path %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html index 1f840771..a80d5c76 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html @@ -5,6 +5,12 @@ {{ section.value|convert_markdown(heading_level, html_id) }} {% elif config.show_docstring_attributes and section.kind.value == "attributes" %} {% include "docstring/attributes.html" with context %} + {% elif config.show_docstring_functions and section.kind.value == "functions" %} + {% include "docstring/functions.html" with context %} + {% elif config.show_docstring_classes and section.kind.value == "classes" %} + {% include "docstring/classes.html" with context %} + {% elif config.show_docstring_modules and section.kind.value == "modules" %} + {% include "docstring/modules.html" with context %} {% elif config.show_docstring_parameters and section.kind.value == "parameters" %} {% include "docstring/parameters.html" with context %} {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html new file mode 100644 index 00000000..720dbe78 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html @@ -0,0 +1,67 @@ +{{ log.debug("Rendering classes section") }} + +{% import "language.html" as lang with context %} + +{% if config.docstring_section_style == "table" %} + {% block table_style %} +

{{ section.title or lang.t("Classes:") }}

+ + + + + + + + + {% for class in section.value %} + + + + + {% endfor %} + +
{{ lang.t("Name") }}{{ lang.t("Description") }}
{{ class.name }} +
+ {{ class.description|convert_markdown(heading_level, html_id) }} +
+
+ {% endblock table_style %} +{% elif config.docstring_section_style == "list" %} + {% block list_style %} +

{{ section.title or lang.t("Classes:") }}

+
    + {% for class in section.value %} +
  • + {{ class.name }} + – +
    + {{ class.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+ {% endblock list_style %} +{% elif config.docstring_section_style == "spacy" %} + {% block spacy_style %} + + + + + + + + + {% for class in section.value %} + + + + + {% endfor %} + +
{{ (section.title or lang.t("CLASS")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
{{ class.name }} +
+ {{ class.description|convert_markdown(heading_level, html_id) }} +
+
+ {% endblock spacy_style %} +{% endif %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html new file mode 100644 index 00000000..970fcbd5 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html @@ -0,0 +1,73 @@ +{{ log.debug("Rendering functions section") }} + +{% import "language.html" as lang with context %} + +{% if config.docstring_section_style == "table" %} + {% block table_style %} +

{{ 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 %} + + + + + {% endif %} + {% endfor %} + +
{{ lang.t("Name") }}{{ lang.t("Description") }}
{{ function.name }} +
+ {{ function.description|convert_markdown(heading_level, html_id) }} +
+
+ {% endblock table_style %} +{% elif config.docstring_section_style == "list" %} + {% block list_style %} +

{{ 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) }} +
    +
    • + {% endif %} + {% endfor %} +
+ {% endblock list_style %} +{% elif config.docstring_section_style == "spacy" %} + {% block spacy_style %} + + + + + + + + + {% for function in section.value %} + {% if not function.name == "__init__" or not config.merge_init_into_class %} + + + + + {% endif %} + {% endfor %} + +
{{ (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) }} +
+
+ {% endblock spacy_style %} +{% endif %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html new file mode 100644 index 00000000..ed102c0c --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html @@ -0,0 +1,67 @@ +{{ log.debug("Rendering modules section") }} + +{% import "language.html" as lang with context %} + +{% if config.docstring_section_style == "table" %} + {% block table_style %} +

{{ section.title or lang.t("Modules:") }}

+ + + + + + + + + {% for module in section.value %} + + + + + {% endfor %} + +
{{ lang.t("Name") }}{{ lang.t("Description") }}
{{ module.name }} +
+ {{ module.description|convert_markdown(heading_level, html_id) }} +
+
+ {% endblock table_style %} +{% elif config.docstring_section_style == "list" %} + {% block list_style %} +

{{ section.title or lang.t("Modules:") }}

+
    + {% for module in section.value %} +
  • + {{ module.name }} + – +
    + {{ module.description|convert_markdown(heading_level, html_id) }} +
    +
    • + {% endfor %} +
+ {% endblock list_style %} +{% elif config.docstring_section_style == "spacy" %} + {% block spacy_style %} + + + + + + + + + {% for module in section.value %} + + + + + {% endfor %} + +
{{ (section.title or lang.t("MODULE")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
{{ module.name }} +
+ {{ module.description|convert_markdown(heading_level, html_id) }} +
+
+ {% endblock spacy_style %} +{% endif %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html b/src/mkdocstrings_handlers/python/templates/material/_base/function.html index 4290b115..a224f4de 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html @@ -3,7 +3,7 @@ {% import "language.html" as lang with context %}
-{% with html_id = function.path %} +{% with obj = function, html_id = function.path %} {% if root %} {% set show_full_path = config.show_root_full_path %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html index 2e50607b..1f76e059 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html @@ -1,29 +1,37 @@ {% macro t(key) %}{{ { - "ATTRIBUTE": "ATTRIBUTE", - "Attributes:": "Attributes:", - "DEFAULT:": "DEFAULT:", - "Default": "Default", - "default:": "default:", - "DESCRIPTION": "DESCRIPTION", - "Description": "Description", - "Examples:": "Examples:", - "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", - "WARNS": "WARNS", - "Warns:": "Warns:", - "YIELDS": "YIELDS", - "Yields:": "Yields:", - }[key] }}{% endmacro %} \ No newline at end of file + "ATTRIBUTE": "ATTRIBUTE", + "Attributes:": "Attributes:", + "Classes:": "Classes:", + "CLASS": "CLASS", + "DEFAULT:": "DEFAULT:", + "Default": "Default", + "default:": "default:", + "DESCRIPTION": "DESCRIPTION", + "Description": "Description", + "Examples:": "Examples:", + "Functions:": "Functions:", + "FUNCTION": "FUNCTION", + "Methods:": "Methods:", + "METHOD": "METHOD", + "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", + "WARNS": "WARNS", + "Warns:": "Warns:", + "YIELDS": "YIELDS", + "Yields:": "Yields:", +}[key] }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html index 3698b81a..456e1170 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html @@ -2,12 +2,20 @@ {% macro t(key) %}{{ { "ATTRIBUTE": "属性", "Attributes:": "属性：", + "Classes:": "", + "CLASS": "", "DEFAULT:": "デフォルト：", "Default": "デフォルト", "default:": "デフォルト：", "DESCRIPTION": "デスクリプション", "Description": "デスクリプション", "Examples:": "例：", + "Functions:": "", + "FUNCTION": "", + "Methods:": "", + "METHOD": "", + "Modules:": "", + "MODULE": "", "Name": "名前", "Other Parameters:": "他の引数：", "PARAMETER": "引数", diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html index e66fa2e2..9c018f27 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html @@ -1,29 +1,37 @@ {% macro t(key) %}{{ { - "ATTRIBUTE": "属性", - "Attributes:": "属性：", - "DEFAULT:": "默认：", - "Default": "默认", - "default:": "默认：", - "DESCRIPTION": "描述", - "Description": "描述", - "Examples:": "示例：", - "Name": "名称", - "Other Parameters:": "其他参数：", - "PARAMETER": "参数", - "Parameters:": "参数：", - "RAISES": "引发", - "Raises:" : "引发：", - "Receives:": "接收：", - "RECEIVES": "接收", - "required": "必需", - "RETURNS": "返回", - "Returns:": "返回：", - "Source code in": "源代码位于：", - "TYPE:": "类型：", - "Type": "类型", - "Warns:": "警告：", - "WARNS": "警告", - "YIELDS": "产生", - "Yields:": "产生：", - }[key] }}{% endmacro %} \ No newline at end of file + "ATTRIBUTE": "属性", + "Attributes:": "属性：", + "Classes:": "", + "CLASS": "", + "DEFAULT:": "默认：", + "Default": "默认", + "default:": "默认：", + "DESCRIPTION": "描述", + "Description": "描述", + "Examples:": "示例：", + "Functions:": "", + "FUNCTION": "", + "Methods:": "", + "METHOD": "", + "Modules:": "", + "MODULE": "", + "Name": "名称", + "Other Parameters:": "其他参数：", + "PARAMETER": "参数", + "Parameters:": "参数：", + "RAISES": "引发", + "Raises:" : "引发：", + "Receives:": "接收：", + "RECEIVES": "接收", + "required": "必需", + "RETURNS": "返回", + "Returns:": "返回：", + "Source code in": "源代码位于：", + "TYPE:": "类型：", + "Type": "类型", + "Warns:": "警告：", + "WARNS": "警告", + "YIELDS": "产生", + "Yields:": "产生：", +}[key] }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html b/src/mkdocstrings_handlers/python/templates/material/_base/module.html index 299b4941..ce62f8e7 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html @@ -1,7 +1,7 @@ {{ log.debug("Rendering " + module.path) }}
-{% with html_id = module.path %} +{% with obj = module, html_id = module.path %} {% if root %} {% set show_full_path = config.show_root_full_path %} diff --git a/src/mkdocstrings_handlers/python/templates/material/docstring/classes.html b/src/mkdocstrings_handlers/python/templates/material/docstring/classes.html new file mode 100644 index 00000000..f92bdb60 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/docstring/classes.html @@ -0,0 +1 @@ +{% extends "_base/docstring/classes.html" %} diff --git a/src/mkdocstrings_handlers/python/templates/material/docstring/functions.html b/src/mkdocstrings_handlers/python/templates/material/docstring/functions.html new file mode 100644 index 00000000..4621cc92 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/docstring/functions.html @@ -0,0 +1 @@ +{% extends "_base/docstring/functions.html" %} diff --git a/src/mkdocstrings_handlers/python/templates/material/docstring/modules.html b/src/mkdocstrings_handlers/python/templates/material/docstring/modules.html new file mode 100644 index 00000000..0d8ef4d5 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/docstring/modules.html @@ -0,0 +1 @@ +{% extends "_base/docstring/modules.html" %} From 5d834fa87f629fd75c4b48d7096b21b47025d043 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 20 Aug 2023 17:12:10 +0200 Subject: [PATCH 2/3] docs: Format code snippets --- docs/usage/configuration/general.md | 3 ++- docs/usage/configuration/members.md | 31 ++++++++++++++++++++++++----- docs/usage/customization.md | 6 +++++- 3 files changed, 33 insertions(+), 7 deletions(-) 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 955420b6..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/). From 20be8f8ab3b5656be1aae281a60889453517a678 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 20 Aug 2023 17:21:23 +0200 Subject: [PATCH 3/3] chore: Prepare release 1.5.0 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6deb264..a6051524 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [1.5.0](https://github.com/mkdocstrings/python/releases/tag/1.5.0) - 2023-08-20 + +[Compare with 1.4.0](https://github.com/mkdocstrings/python/compare/1.4.0...1.5.0) + +### Features + +- Add support for new Griffe docstring sections: modules, classes, and functions (methods) ([d5337af](https://github.com/mkdocstrings/python/commit/d5337afdf68fc492b34f749aa69d1da33b49f9c2) by Timothée Mazzucotelli). + ## [1.4.0](https://github.com/mkdocstrings/python/releases/tag/1.4.0) - 2023-08-18 [Compare with 1.3.0](https://github.com/mkdocstrings/python/compare/1.3.0...1.4.0)