From b4fb4dbab38afcef03a2a34411b347aa59292ca0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 11 Dec 2022 16:12:47 +0100 Subject: [PATCH 1/5] chore: Add JSON schema for handler's options --- docs/schema.json | 169 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 docs/schema.json diff --git a/docs/schema.json b/docs/schema.json new file mode 100644 index 00000000..d1a49430 --- /dev/null +++ b/docs/schema.json @@ -0,0 +1,169 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema", + "title": "Python handler for mkdocstrings.", + "type": "object", + "properties": { + "python": { + "markdownDescription": "https://mkdocstrings.github.io/python/", + "type": "object", + "properties": { + "custom_templates": { + "title": "The path to a directory containing custom templates. The path is relative to the current working directory.", + "markdownDescription": "https://mkdocstrings.github.io/theming/", + "type": "string", + "default": null, + "format": "path" + }, + "docstring_style": { + "title": "The docstring style to use when parsing docstrings.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "enum": ["google", "numpy", "sphinx"], + "default": "google" + }, + "docstring_options": { + "title": "The options for the docstring parser.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "default": null, + "items": { + "$ref": "https://raw.githubusercontent.com/mkdocstrings/griffe/master/docs/schema-docstrings-options.json" + } + }, + "show_root_heading": { + "title": "Show the heading of the object at the root of the documentation tree.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_root_toc_entry": { + "title": "If the root heading is not shown, at least add a ToC entry for it.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_root_full_path": { + "title": "Show the full Python path for the root object heading.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_root_members_full_path": { + "title": "Show the full Python path of the root members.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_object_full_path": { + "title": "Show the full Python path of every object.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_category_heading": { + "title": "When grouped by categories, show a heading for each category.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_if_no_docstring": { + "title": "Show the object heading even if it has no docstring or children with docstrings.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_signature": { + "title": "Show methods and functions signatures.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_signature_annotations": { + "title": "Show the type annotations in methods and functions signatures.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "separate_signature": { + "title": "Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "line_length": { + "title": "Maximum line length when formatting code/signatures.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "integer", + "default": 60 + }, + "merge_init_into_class": { + "title": "Whether to merge the `__init__` method into the class' signature and docstring.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_source": { + "title": "Show the source code of this object..", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_bases": { + "title": "Show the base classes of a class.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_submodules": { + "title": "When rendering a module, show its submodules recursively.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "group_by_category": { + "title": "Group the object's children by categories: attributes, classes, functions, and modules.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "heading_level": { + "title": "The initial heading level to use.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "integer", + "default": 2 + }, + "members_order": { + "title": "The members ordering to use.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "enum": ["alphabetical", "source"], + "default": "alphabetical" + }, + "docstring_section_style": { + "title": "The style used to render docstring sections.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "enum": ["list", "spacy", "table"], + "default": "table" + }, + "members": { + "title": "An explicit list of members to render.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": [ + "boolean", + "array" + ], + "default": null + }, + "filters": { + "title": "A list of filters applied to filter objects based on their name. A filter starting with `!` will exclude matching objects instead of including them. The `members` option takes precedence over `filters` (filters will still be applied recursively to lower members in the hierarchy).", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "array", + "default": ["!^_[^_]"] + }, + "annotations_path": { + "title": "The verbosity for annotations path.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "enum": ["brief", "source"], + "default": "brief" + } + } + } + } +} \ No newline at end of file From 5b821e3771cb581e95352f85a31b9bacfe643751 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 11 Dec 2022 16:18:29 +0100 Subject: [PATCH 2/5] chore: Disallow additional properties in JSON schema --- docs/schema.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/schema.json b/docs/schema.json index d1a49430..b19c5c8c 100644 --- a/docs/schema.json +++ b/docs/schema.json @@ -163,7 +163,9 @@ "enum": ["brief", "source"], "default": "brief" } - } + }, + "additionalProperties": false } - } + }, + "additionalProperties": false } \ No newline at end of file From 96e231ad24657475cc1f72e5a5c44a9451612abf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 11 Dec 2022 16:55:11 +0100 Subject: [PATCH 3/5] chore: Fix JSON schema --- docs/schema.json | 335 ++++++++++++++++++++++++++--------------------- 1 file changed, 185 insertions(+), 150 deletions(-) diff --git a/docs/schema.json b/docs/schema.json index b19c5c8c..a68b9041 100644 --- a/docs/schema.json +++ b/docs/schema.json @@ -7,161 +7,196 @@ "markdownDescription": "https://mkdocstrings.github.io/python/", "type": "object", "properties": { - "custom_templates": { - "title": "The path to a directory containing custom templates. The path is relative to the current working directory.", - "markdownDescription": "https://mkdocstrings.github.io/theming/", - "type": "string", - "default": null, - "format": "path" - }, - "docstring_style": { - "title": "The docstring style to use when parsing docstrings.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "enum": ["google", "numpy", "sphinx"], - "default": "google" - }, - "docstring_options": { - "title": "The options for the docstring parser.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "default": null, + "import": { + "title": "Inventories to import.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#global-only-options", + "type": "array", "items": { - "$ref": "https://raw.githubusercontent.com/mkdocstrings/griffe/master/docs/schema-docstrings-options.json" + "oneOf": [ + { + "type": "string" + }, + { + "type": "object", + "properties": { + "url": { + "title": "URL of the inventory file.", + "type": "string" + }, + "base_url": { + "title": "Base URL used to build references URLs.", + "type": "string" + } + } + } + ] } }, - "show_root_heading": { - "title": "Show the heading of the object at the root of the documentation tree.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "show_root_toc_entry": { - "title": "If the root heading is not shown, at least add a ToC entry for it.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": true - }, - "show_root_full_path": { - "title": "Show the full Python path for the root object heading.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": true - }, - "show_root_members_full_path": { - "title": "Show the full Python path of the root members.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "show_object_full_path": { - "title": "Show the full Python path of every object.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "show_category_heading": { - "title": "When grouped by categories, show a heading for each category.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "show_if_no_docstring": { - "title": "Show the object heading even if it has no docstring or children with docstrings.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "show_signature": { - "title": "Show methods and functions signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": true - }, - "show_signature_annotations": { - "title": "Show the type annotations in methods and functions signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "separate_signature": { - "title": "Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "line_length": { - "title": "Maximum line length when formatting code/signatures.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "integer", - "default": 60 - }, - "merge_init_into_class": { - "title": "Whether to merge the `__init__` method into the class' signature and docstring.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "show_source": { - "title": "Show the source code of this object..", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": true - }, - "show_bases": { - "title": "Show the base classes of a class.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": true - }, - "show_submodules": { - "title": "When rendering a module, show its submodules recursively.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": false - }, - "group_by_category": { - "title": "Group the object's children by categories: attributes, classes, functions, and modules.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "boolean", - "default": true - }, - "heading_level": { - "title": "The initial heading level to use.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": "integer", - "default": 2 - }, - "members_order": { - "title": "The members ordering to use.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "enum": ["alphabetical", "source"], - "default": "alphabetical" - }, - "docstring_section_style": { - "title": "The style used to render docstring sections.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "enum": ["list", "spacy", "table"], - "default": "table" - }, - "members": { - "title": "An explicit list of members to render.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "type": [ - "boolean", - "array" - ], - "default": null - }, - "filters": { - "title": "A list of filters applied to filter objects based on their name. A filter starting with `!` will exclude matching objects instead of including them. The `members` option takes precedence over `filters` (filters will still be applied recursively to lower members in the hierarchy).", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "paths": { + "title": "Local absolute/relative paths (relative to mkdocs.yml) to search packages into.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#global-only-options", "type": "array", - "default": ["!^_[^_]"] + "items": { + "type": "string", + "format": "path" + } }, - "annotations_path": { - "title": "The verbosity for annotations path.", - "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", - "enum": ["brief", "source"], - "default": "brief" + "options": { + "title": "Options for collecting and rendering objects.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "object", + "properties": { + "docstring_style": { + "title": "The docstring style to use when parsing docstrings.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "enum": ["google", "numpy", "sphinx"], + "default": "google" + }, + "docstring_options": { + "title": "The options for the docstring parser.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "default": null, + "items": { + "$ref": "https://raw.githubusercontent.com/mkdocstrings/griffe/master/docs/schema-docstrings-options.json" + } + }, + "show_root_heading": { + "title": "Show the heading of the object at the root of the documentation tree.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_root_toc_entry": { + "title": "If the root heading is not shown, at least add a ToC entry for it.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_root_full_path": { + "title": "Show the full Python path for the root object heading.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_root_members_full_path": { + "title": "Show the full Python path of the root members.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_object_full_path": { + "title": "Show the full Python path of every object.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_category_heading": { + "title": "When grouped by categories, show a heading for each category.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_if_no_docstring": { + "title": "Show the object heading even if it has no docstring or children with docstrings.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_signature": { + "title": "Show methods and functions signatures.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_signature_annotations": { + "title": "Show the type annotations in methods and functions signatures.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "separate_signature": { + "title": "Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "line_length": { + "title": "Maximum line length when formatting code/signatures.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "integer", + "default": 60 + }, + "merge_init_into_class": { + "title": "Whether to merge the `__init__` method into the class' signature and docstring.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "show_source": { + "title": "Show the source code of this object..", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_bases": { + "title": "Show the base classes of a class.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "show_submodules": { + "title": "When rendering a module, show its submodules recursively.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": false + }, + "group_by_category": { + "title": "Group the object's children by categories: attributes, classes, functions, and modules.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "boolean", + "default": true + }, + "heading_level": { + "title": "The initial heading level to use.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "integer", + "default": 2 + }, + "members_order": { + "title": "The members ordering to use.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "enum": ["alphabetical", "source"], + "default": "alphabetical" + }, + "docstring_section_style": { + "title": "The style used to render docstring sections.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "enum": ["list", "spacy", "table"], + "default": "table" + }, + "members": { + "title": "An explicit list of members to render.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": [ + "boolean", + "array" + ], + "default": null + }, + "filters": { + "title": "A list of filters applied to filter objects based on their name. A filter starting with `!` will exclude matching objects instead of including them. The `members` option takes precedence over `filters` (filters will still be applied recursively to lower members in the hierarchy).", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "type": "array", + "default": ["!^_[^_]"] + }, + "annotations_path": { + "title": "The verbosity for annotations path.", + "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options", + "enum": ["brief", "source"], + "default": "brief" + } + }, + "additionalProperties": false } }, "additionalProperties": false From dccb818f51278cc8799e2187a615d999a3ab86fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 4 Jan 2023 22:32:47 +0100 Subject: [PATCH 4/5] refactor: Change unresolved aliases log level to DEBUG --- src/mkdocstrings_handlers/python/handler.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index afb8ed98..940f2731 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -216,7 +216,8 @@ def collect(self, identifier: str, config: dict) -> CollectorItem: # noqa: D102 unresolved, iterations = loader.resolve_aliases(implicit=False, external=False) if unresolved: - logger.warning(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations") + logger.debug(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations") + logger.debug(f"Unresolved aliases: {', '.join(sorted(unresolved))}") try: doc_object = self._modules_collection[identifier] From 4ce0fc824fc36cadcf2b70cc72b627bdaa5abd65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 4 Jan 2023 22:33:48 +0100 Subject: [PATCH 5/5] chore: Prepare release 0.8.3 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f9f2c8c3..28ea412e 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). +## [0.8.3](https://github.com/mkdocstrings/python/releases/tag/0.8.3) - 2023-01-04 + +[Compare with 0.8.2](https://github.com/mkdocstrings/python/compare/0.8.2...0.8.3) + +### Code Refactoring +- Change "unresolved aliases" log level to DEBUG ([dccb818](https://github.com/mkdocstrings/python/commit/dccb818f51278cc8799e2187a615d999a3ab86fb) by Timothée Mazzucotelli). + + ## [0.8.2](https://github.com/mkdocstrings/python/releases/tag/0.8.2) - 2022-11-19 [Compare with 0.8.1](https://github.com/mkdocstrings/python/compare/0.8.1...0.8.2)