From f299b212e6771b371408200c424473f8257dafad Mon Sep 17 00:00:00 2001 From: chrimaho Date: Sat, 24 Jan 2026 19:45:23 +1100 Subject: [PATCH 1/9] Add schema for `docstring-format-checker` - Introduce `partial-dfc.json` schema for the `docstring-format-checker` package. - Reference the new schema in `pyproject.json` under `dfc` and `docstring-format-checker`. - Provide detailed properties for configuration options in the schema. --- src/schemas/json/partial-dfc.json | 111 ++++++++++++++++++++++++++++++ src/schemas/json/pyproject.json | 10 +++ 2 files changed, 121 insertions(+) create mode 100644 src/schemas/json/partial-dfc.json diff --git a/src/schemas/json/partial-dfc.json b/src/schemas/json/partial-dfc.json new file mode 100644 index 00000000000..bcc874f8763 --- /dev/null +++ b/src/schemas/json/partial-dfc.json @@ -0,0 +1,111 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://json.schemastore.org/partial-dfc.json", + "$comment": "This is a partial schema for the `docstring-format-checker` package pyproject.toml, under the header [tool.dfc] or [tool.docstring-format-checker].", + "type": "object", + "additionalProperties": false, + "properties": { + "allow_undefined_sections": { + "title": "Allow Undefined Sections", + "description": "Allow sections not defined in the configuration.", + "type": "boolean", + "default": false + }, + "require_docstrings": { + "title": "Require Docstrings", + "description": "Require docstrings for all functions/methods.", + "type": "boolean", + "default": true + }, + "check_private": { + "title": "Check Private Members", + "description": "Check docstrings for private members (starting with an underscore).", + "type": "boolean", + "default": false + }, + "validate_param_types": { + "title": "Validate Parameter Types", + "description": "Validate that parameter types are provided in the docstring.", + "type": "boolean", + "default": true + }, + "optional_style": { + "title": "Optional Style", + "description": "The style for reporting issues in optional sections.", + "type": "string", + "enum": [ + "silent", + "validate", + "strict" + ], + "default": "validate" + }, + "sections": { + "type": "array", + "title": "Docstring Sections", + "description": "List of docstring section configurations.", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "type" + ], + "properties": { + "name": { + "title": "Name", + "description": "Name of the docstring section.", + "type": "string" + }, + "type": { + "title": "Type", + "description": "Type of the section content.", + "type": "string", + "enum": [ + "free_text", + "list_name", + "list_type", + "list_name_and_type" + ] + }, + "order": { + "title": "Order", + "description": "Order of the section in the docstring.", + "type": [ + "integer", + "null" + ], + "default": null + }, + "admonition": { + "title": "Admonition", + "description": "Admonition style for the section. Can be False (no admonition) or a string specifying the admonition type.", + "type": [ + "boolean", + "string" + ], + "default": false + }, + "prefix": { + "title": "Prefix", + "description": "Prefix string for the admonition values.", + "type": "string", + "default": "" + }, + "required": { + "title": "Required", + "description": "Whether this section is required in the docstring.", + "type": "boolean", + "default": false + }, + "message": { + "title": "Message", + "description": "Optional message for validation errors.", + "type": "string", + "default": "" + } + } + } + } + } +} diff --git a/src/schemas/json/pyproject.json b/src/schemas/json/pyproject.json index 75dcf412e66..74d2d3da48e 100644 --- a/src/schemas/json/pyproject.json +++ b/src/schemas/json/pyproject.json @@ -1061,6 +1061,16 @@ "$ref": "https://json.schemastore.org/uv.json", "title": "Package Manager", "description": "An extremely fast Python package installer and resolver, written in Rust." + }, + "dfc": { + "$ref": "https://json.schemastore.org/partial-dfc.json", + "title": "docstring-format-checker", + "description": "A CLI tool to check and validate Python docstring formatting and completeness" + }, + "docstring-format-checker": { + "$ref": "https://json.schemastore.org/partial-dfc.json", + "title": "docstring-format-checker", + "description": "A CLI tool to check and validate Python docstring formatting and completeness" } }, "examples": [ From dcfbfbdfbcab74c61f557fa586103a9698aa8fba Mon Sep 17 00:00:00 2001 From: chrimaho <44449504+chrimaho@users.noreply.github.com> Date: Mon, 26 Jan 2026 15:03:27 +1100 Subject: [PATCH 2/9] Fix formatting for `partial-dfc.json` file - Improve formatting and readability of the JSON schema. - Correct indentation. --- src/schemas/json/partial-dfc.json | 193 ++++++++++++++---------------- 1 file changed, 90 insertions(+), 103 deletions(-) diff --git a/src/schemas/json/partial-dfc.json b/src/schemas/json/partial-dfc.json index bcc874f8763..c100e0eeabd 100644 --- a/src/schemas/json/partial-dfc.json +++ b/src/schemas/json/partial-dfc.json @@ -1,111 +1,98 @@ { - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://json.schemastore.org/partial-dfc.json", - "$comment": "This is a partial schema for the `docstring-format-checker` package pyproject.toml, under the header [tool.dfc] or [tool.docstring-format-checker].", - "type": "object", - "additionalProperties": false, - "properties": { - "allow_undefined_sections": { - "title": "Allow Undefined Sections", - "description": "Allow sections not defined in the configuration.", - "type": "boolean", + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://json.schemastore.org/partial-dfc.json", + "$comment": "This is a partial schema for the `docstring-format-checker` package pyproject.toml, under the header [tool.dfc] or [tool.docstring-format-checker].", + "type": "object", + "additionalProperties": false, + "properties": { + "allow_undefined_sections": { + "title": "Allow Undefined Sections", + "description": "Allow sections not defined in the configuration.", + "type": "boolean", + "default": false + }, + "require_docstrings": { + "title": "Require Docstrings", + "description": "Require docstrings for all functions/methods.", + "type": "boolean", + "default": true + }, + "check_private": { + "title": "Check Private Members", + "description": "Check docstrings for private members (starting with an underscore).", + "type": "boolean", + "default": false + }, + "validate_param_types": { + "title": "Validate Parameter Types", + "description": "Validate that parameter types are provided in the docstring.", + "type": "boolean", + "default": true + }, + "optional_style": { + "title": "Optional Style", + "description": "The style for reporting issues in optional sections.", + "type": "string", + "enum": ["silent", "validate", "strict"], + "default": "validate" + }, + "sections": { + "type": "array", + "title": "Docstring Sections", + "description": "List of docstring section configurations.", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name", "type"], + "properties": { + "name": { + "title": "Name", + "description": "Name of the docstring section.", + "type": "string" + }, + "type": { + "title": "Type", + "description": "Type of the section content.", + "type": "string", + "enum": [ + "free_text", + "list_name", + "list_type", + "list_name_and_type" + ] + }, + "order": { + "title": "Order", + "description": "Order of the section in the docstring.", + "type": ["integer", "null"], + "default": null + }, + "admonition": { + "title": "Admonition", + "description": "Admonition style for the section. Can be False (no admonition) or a string specifying the admonition type.", + "type": ["boolean", "string"], "default": false - }, - "require_docstrings": { - "title": "Require Docstrings", - "description": "Require docstrings for all functions/methods.", - "type": "boolean", - "default": true - }, - "check_private": { - "title": "Check Private Members", - "description": "Check docstrings for private members (starting with an underscore).", + }, + "prefix": { + "title": "Prefix", + "description": "Prefix string for the admonition values.", + "type": "string", + "default": "" + }, + "required": { + "title": "Required", + "description": "Whether this section is required in the docstring.", "type": "boolean", "default": false - }, - "validate_param_types": { - "title": "Validate Parameter Types", - "description": "Validate that parameter types are provided in the docstring.", - "type": "boolean", - "default": true - }, - "optional_style": { - "title": "Optional Style", - "description": "The style for reporting issues in optional sections.", + }, + "message": { + "title": "Message", + "description": "Optional message for validation errors.", "type": "string", - "enum": [ - "silent", - "validate", - "strict" - ], - "default": "validate" - }, - "sections": { - "type": "array", - "title": "Docstring Sections", - "description": "List of docstring section configurations.", - "items": { - "type": "object", - "additionalProperties": false, - "required": [ - "name", - "type" - ], - "properties": { - "name": { - "title": "Name", - "description": "Name of the docstring section.", - "type": "string" - }, - "type": { - "title": "Type", - "description": "Type of the section content.", - "type": "string", - "enum": [ - "free_text", - "list_name", - "list_type", - "list_name_and_type" - ] - }, - "order": { - "title": "Order", - "description": "Order of the section in the docstring.", - "type": [ - "integer", - "null" - ], - "default": null - }, - "admonition": { - "title": "Admonition", - "description": "Admonition style for the section. Can be False (no admonition) or a string specifying the admonition type.", - "type": [ - "boolean", - "string" - ], - "default": false - }, - "prefix": { - "title": "Prefix", - "description": "Prefix string for the admonition values.", - "type": "string", - "default": "" - }, - "required": { - "title": "Required", - "description": "Whether this section is required in the docstring.", - "type": "boolean", - "default": false - }, - "message": { - "title": "Message", - "description": "Optional message for validation errors.", - "type": "string", - "default": "" - } - } - } + "default": "" + } } + } } + } } From e80d719dd570e8183d21cd57724bbba9a63fb1ba Mon Sep 17 00:00:00 2001 From: chrimaho <44449504+chrimaho@users.noreply.github.com> Date: Mon, 26 Jan 2026 15:08:51 +1100 Subject: [PATCH 3/9] Add catalog records for `docstring-format-checker` and `dfc` schemas - Introduce schema for `docstring-format-checker` with description and URL. - Introduce schema for `dfc` with description and URL. --- src/api/json/catalog.json | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/api/json/catalog.json b/src/api/json/catalog.json index c11de3fc83e..09f308c39ed 100644 --- a/src/api/json/catalog.json +++ b/src/api/json/catalog.json @@ -9247,6 +9247,16 @@ "description": "pgxgen configuration file", "fileMatch": ["pgxgen.yml", "pgxgen.yaml"], "url": "https://raw.githubusercontent.com/tkcrm/pgxgen/refs/heads/master/schemas/pgxgen-schema.json" + }, + { + "name": "docstring-format-checker", + "description": "A CLI tool to check and validate Python docstring formatting and completeness", + "url": "https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/partial-dfc.json" + }, + { + "name": "dfc", + "description": "A CLI tool to check and validate Python docstring formatting and completeness", + "url": "https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/partial-dfc.json" } ] } From 4e55c804e9d8c9a2873ba39834571df5dda0b350 Mon Sep 17 00:00:00 2001 From: chrimaho <44449504+chrimaho@users.noreply.github.com> Date: Mon, 26 Jan 2026 15:17:50 +1100 Subject: [PATCH 4/9] Fix type declaration for `admonition` values in the `dfc` schema - Resolving failing `ajv` validation checks: - Error message: - `strict mode: use allowUnionTypes to allow union type keyword at "https://json.schemastore.org/partial-dfc.json#/properties/sections/items/properties/admonition" (strictTypes)` - This means Ajv validation doesn't allow union types (e.g., `"type": ["boolean", "string"]`) by default under strict mode. - Solution: Replace the union type definition for the "admonition" property with a `oneOf` clause. - Here, the solution provides one of `"boolean"` with only the `false` value, or `"string"` otherwise. --- src/schemas/json/partial-dfc.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/schemas/json/partial-dfc.json b/src/schemas/json/partial-dfc.json index c100e0eeabd..91ff5fb68f1 100644 --- a/src/schemas/json/partial-dfc.json +++ b/src/schemas/json/partial-dfc.json @@ -70,7 +70,10 @@ "admonition": { "title": "Admonition", "description": "Admonition style for the section. Can be False (no admonition) or a string specifying the admonition type.", - "type": ["boolean", "string"], + "oneOf": [ + { "type": "boolean", "enum": [false] }, + { "type": "string" } + ], "default": false }, "prefix": { From 73ad56caa46ecca61bad0a2dcf30b93fa4154bd1 Mon Sep 17 00:00:00 2001 From: chrimaho <44449504+chrimaho@users.noreply.github.com> Date: Sat, 7 Feb 2026 17:01:53 +1100 Subject: [PATCH 5/9] Fix schema references and catalog ordering for `dfc` - Introduce schema entries for `dfc` and `docstring-format-checker` in the catalog. - Reorder entries for `docstring-format-checker` and `dfc`. - Add `partial-dfc.json` to the schema validation file match list. - Create a new configuration file for `docstring-format-checker`. --- src/api/json/catalog.json | 22 ++++++++++++---------- src/schema-validation.jsonc | 1 + 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/src/api/json/catalog.json b/src/api/json/catalog.json index 09f308c39ed..cce5ece7414 100644 --- a/src/api/json/catalog.json +++ b/src/api/json/catalog.json @@ -1607,6 +1607,18 @@ "fileMatch": ["devbox-plugin.json"], "url": "https://raw.githubusercontent.com/jetify-com/devbox/main/.schema/devbox-plugin.schema.json" }, + { + "name": "dfc", + "description": "A CLI tool to check and validate Python docstring formatting and completeness", + "fileMatch": [], + "url": "https://json.schemastore.org/partial-dfc.json" + }, + { + "name": "docstring-format-checker", + "description": "A CLI tool to check and validate Python docstring formatting and completeness", + "fileMatch": [], + "url": "https://json.schemastore.org/partial-dfc.json" + }, { "name": "Drupal Breakpoints", "description": "Drupal configuration for breakpoints", @@ -9247,16 +9259,6 @@ "description": "pgxgen configuration file", "fileMatch": ["pgxgen.yml", "pgxgen.yaml"], "url": "https://raw.githubusercontent.com/tkcrm/pgxgen/refs/heads/master/schemas/pgxgen-schema.json" - }, - { - "name": "docstring-format-checker", - "description": "A CLI tool to check and validate Python docstring formatting and completeness", - "url": "https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/partial-dfc.json" - }, - { - "name": "dfc", - "description": "A CLI tool to check and validate Python docstring formatting and completeness", - "url": "https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/partial-dfc.json" } ] } diff --git a/src/schema-validation.jsonc b/src/schema-validation.jsonc index 24802e523b5..e6147a4f344 100644 --- a/src/schema-validation.jsonc +++ b/src/schema-validation.jsonc @@ -1167,6 +1167,7 @@ "maturin.json", "partial-black.json", "partial-cibuildwheel.json", + "partial-dfc.json", "partial-mypy.json", "partial-pdm.json", "partial-pdm-dockerize.json", From 188f1ad8fece5b7da8132051d16e4e820f9030d3 Mon Sep 17 00:00:00 2001 From: Chris Mahoney <44449504+chrimaho@users.noreply.github.com> Date: Sat, 18 Apr 2026 11:51:22 +1000 Subject: [PATCH 6/9] Remove `dfc` and `docstring-format-checker` entries from `catalog.json` --- src/api/json/catalog.json | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/src/api/json/catalog.json b/src/api/json/catalog.json index cce5ece7414..c11de3fc83e 100644 --- a/src/api/json/catalog.json +++ b/src/api/json/catalog.json @@ -1607,18 +1607,6 @@ "fileMatch": ["devbox-plugin.json"], "url": "https://raw.githubusercontent.com/jetify-com/devbox/main/.schema/devbox-plugin.schema.json" }, - { - "name": "dfc", - "description": "A CLI tool to check and validate Python docstring formatting and completeness", - "fileMatch": [], - "url": "https://json.schemastore.org/partial-dfc.json" - }, - { - "name": "docstring-format-checker", - "description": "A CLI tool to check and validate Python docstring formatting and completeness", - "fileMatch": [], - "url": "https://json.schemastore.org/partial-dfc.json" - }, { "name": "Drupal Breakpoints", "description": "Drupal configuration for breakpoints", From 01da542610bd20eeedd391c03896baeba6c81c4d Mon Sep 17 00:00:00 2001 From: Chris Mahoney <44449504+chrimaho@users.noreply.github.com> Date: Sat, 18 Apr 2026 11:53:38 +1000 Subject: [PATCH 7/9] Add `partial-dfc.json` to `schema-validation.jsonc` --- src/schema-validation.jsonc | 1 + 1 file changed, 1 insertion(+) diff --git a/src/schema-validation.jsonc b/src/schema-validation.jsonc index e6147a4f344..e4c524661bd 100644 --- a/src/schema-validation.jsonc +++ b/src/schema-validation.jsonc @@ -318,6 +318,7 @@ "partial-setuptools-scm.json", // pyproject.json[tool.setuptools-scm] "partial-scikit-build.json", // pyproject.json[tool.scikit-build] "partial-cibuildwheel.json", // pyproject.json[tool.cibuildwheel] + "partial-dfc.json", // pyproject.json[tool.dfc] "partial-mypy.json", // pyproject.json[tool.mypy] "partial-pdm.json", // pyproject.json[tool.pdm] "partial-pdm-dockerize.json", // pyproject.json[tool.pdm.dockerize] From 069451535e86a64e85fbd491d72610901359906f Mon Sep 17 00:00:00 2001 From: Chris Mahoney <44449504+chrimaho@users.noreply.github.com> Date: Sat, 18 Apr 2026 11:56:25 +1000 Subject: [PATCH 8/9] Add `dfc.toml` configuration to `pyproject` tests --- src/test/pyproject/dfc.toml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 src/test/pyproject/dfc.toml diff --git a/src/test/pyproject/dfc.toml b/src/test/pyproject/dfc.toml new file mode 100644 index 00000000000..41f8c52ef96 --- /dev/null +++ b/src/test/pyproject/dfc.toml @@ -0,0 +1,36 @@ +#:schema ../../schemas/json/pyproject.json +[tool.dfc] +allow_undefined_sections = true +require_docstrings = true +check_private = false +validate_param_types = true +optional_style = "validate" + +[[tool.dfc.sections]] +name = "Args" +type = "list_name_and_type" +order = 1 +admonition = false +required = true + +[[tool.dfc.sections]] +name = "Returns" +type = "list_type" +order = 2 +admonition = "note" +prefix = "Return value:" +required = false +message = "Missing returns section" + +[[tool.dfc.sections]] +name = "Raises" +type = "list_name" +order = 3 +required = false + +[[tool.dfc.sections]] +name = "Examples" +type = "free_text" +order = 4 +admonition = "example" +required = false From 0fd224cdc652d43523db951406d5d9c7a4ce26ea Mon Sep 17 00:00:00 2001 From: Chris Mahoney <44449504+chrimaho@users.noreply.github.com> Date: Sat, 18 Apr 2026 11:58:04 +1000 Subject: [PATCH 9/9] Add `docstring-format-checker.toml` to `pyproject` tests --- .../pyproject/docstring-format-checker.toml | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 src/test/pyproject/docstring-format-checker.toml diff --git a/src/test/pyproject/docstring-format-checker.toml b/src/test/pyproject/docstring-format-checker.toml new file mode 100644 index 00000000000..cdfcec52b09 --- /dev/null +++ b/src/test/pyproject/docstring-format-checker.toml @@ -0,0 +1,41 @@ +#:schema ../../schemas/json/pyproject.json +[tool.docstring-format-checker] +allow_undefined_sections = false +require_docstrings = true +check_private = true +validate_param_types = true +optional_style = "strict" + +[[tool.docstring-format-checker.sections]] +name = "Parameters" +type = "list_name_and_type" +order = 1 +required = true +admonition = false + +[[tool.docstring-format-checker.sections]] +name = "Returns" +type = "list_type" +order = 2 +required = true +admonition = "info" +prefix = "Returns:" +message = "Return type documentation is required" + +[[tool.docstring-format-checker.sections]] +name = "Raises" +type = "list_name" +order = 3 +required = false + +[[tool.docstring-format-checker.sections]] +name = "Yields" +type = "list_type" +order = 4 +required = false + +[[tool.docstring-format-checker.sections]] +name = "Note" +type = "free_text" +admonition = "note" +required = false