diff --git a/src/schema-validation.jsonc b/src/schema-validation.jsonc index 3f88b0f33ea..4f221b4ba3c 100644 --- a/src/schema-validation.jsonc +++ b/src/schema-validation.jsonc @@ -331,6 +331,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-fastapi.json", // pyproject.json[tool.fastapi] "partial-mypy.json", // pyproject.json[tool.mypy] "partial-pdm.json", // pyproject.json[tool.pdm] @@ -1270,6 +1271,7 @@ "maturin.json", "partial-black.json", "partial-cibuildwheel.json", + "partial-dfc.json", "partial-fastapi.json", "partial-mypy.json", "partial-pdm.json", diff --git a/src/schemas/json/partial-dfc.json b/src/schemas/json/partial-dfc.json new file mode 100644 index 00000000000..91ff5fb68f1 --- /dev/null +++ b/src/schemas/json/partial-dfc.json @@ -0,0 +1,101 @@ +{ + "$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.", + "oneOf": [ + { "type": "boolean", "enum": [false] }, + { "type": "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 e5f7f34e394..d492912e377 100644 --- a/src/schemas/json/pyproject.json +++ b/src/schemas/json/pyproject.json @@ -1071,6 +1071,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": [ 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 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