Skip to content

Commit 76eb19f

Browse files
chrimahochrimaho
authored
Add schema for docstring-format-checker (#5309)
1 parent 4a030d4 commit 76eb19f

File tree

5 files changed

+190
-0
lines changed

5 files changed

+190
-0
lines changed

‎src/schema-validation.jsonc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -331,6 +331,7 @@
331331
"partial-setuptools-scm.json", // pyproject.json[tool.setuptools-scm]
332332
"partial-scikit-build.json", // pyproject.json[tool.scikit-build]
333333
"partial-cibuildwheel.json", // pyproject.json[tool.cibuildwheel]
334+
"partial-dfc.json", // pyproject.json[tool.dfc]
334335
"partial-fastapi.json", // pyproject.json[tool.fastapi]
335336
"partial-mypy.json", // pyproject.json[tool.mypy]
336337
"partial-pdm.json", // pyproject.json[tool.pdm]
@@ -1270,6 +1271,7 @@
12701271
"maturin.json",
12711272
"partial-black.json",
12721273
"partial-cibuildwheel.json",
1274+
"partial-dfc.json",
12731275
"partial-fastapi.json",
12741276
"partial-mypy.json",
12751277
"partial-pdm.json",

‎src/schemas/json/partial-dfc.json‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://json.schemastore.org/partial-dfc.json",
4+
"$comment": "This is a partial schema for the `docstring-format-checker` package pyproject.toml, under the header [tool.dfc] or [tool.docstring-format-checker].",
5+
"type": "object",
6+
"additionalProperties": false,
7+
"properties": {
8+
"allow_undefined_sections": {
9+
"title": "Allow Undefined Sections",
10+
"description": "Allow sections not defined in the configuration.",
11+
"type": "boolean",
12+
"default": false
13+
},
14+
"require_docstrings": {
15+
"title": "Require Docstrings",
16+
"description": "Require docstrings for all functions/methods.",
17+
"type": "boolean",
18+
"default": true
19+
},
20+
"check_private": {
21+
"title": "Check Private Members",
22+
"description": "Check docstrings for private members (starting with an underscore).",
23+
"type": "boolean",
24+
"default": false
25+
},
26+
"validate_param_types": {
27+
"title": "Validate Parameter Types",
28+
"description": "Validate that parameter types are provided in the docstring.",
29+
"type": "boolean",
30+
"default": true
31+
},
32+
"optional_style": {
33+
"title": "Optional Style",
34+
"description": "The style for reporting issues in optional sections.",
35+
"type": "string",
36+
"enum": ["silent", "validate", "strict"],
37+
"default": "validate"
38+
},
39+
"sections": {
40+
"type": "array",
41+
"title": "Docstring Sections",
42+
"description": "List of docstring section configurations.",
43+
"items": {
44+
"type": "object",
45+
"additionalProperties": false,
46+
"required": ["name", "type"],
47+
"properties": {
48+
"name": {
49+
"title": "Name",
50+
"description": "Name of the docstring section.",
51+
"type": "string"
52+
},
53+
"type": {
54+
"title": "Type",
55+
"description": "Type of the section content.",
56+
"type": "string",
57+
"enum": [
58+
"free_text",
59+
"list_name",
60+
"list_type",
61+
"list_name_and_type"
62+
]
63+
},
64+
"order": {
65+
"title": "Order",
66+
"description": "Order of the section in the docstring.",
67+
"type": ["integer", "null"],
68+
"default": null
69+
},
70+
"admonition": {
71+
"title": "Admonition",
72+
"description": "Admonition style for the section. Can be False (no admonition) or a string specifying the admonition type.",
73+
"oneOf": [
74+
{ "type": "boolean", "enum": [false] },
75+
{ "type": "string" }
76+
],
77+
"default": false
78+
},
79+
"prefix": {
80+
"title": "Prefix",
81+
"description": "Prefix string for the admonition values.",
82+
"type": "string",
83+
"default": ""
84+
},
85+
"required": {
86+
"title": "Required",
87+
"description": "Whether this section is required in the docstring.",
88+
"type": "boolean",
89+
"default": false
90+
},
91+
"message": {
92+
"title": "Message",
93+
"description": "Optional message for validation errors.",
94+
"type": "string",
95+
"default": ""
96+
}
97+
}
98+
}
99+
}
100+
}
101+
}

‎src/schemas/json/pyproject.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1071,6 +1071,16 @@
10711071
"$ref": "https://json.schemastore.org/uv.json",
10721072
"title": "Package Manager",
10731073
"description": "An extremely fast Python package installer and resolver, written in Rust."
1074+
},
1075+
"dfc": {
1076+
"$ref": "https://json.schemastore.org/partial-dfc.json",
1077+
"title": "docstring-format-checker",
1078+
"description": "A CLI tool to check and validate Python docstring formatting and completeness"
1079+
},
1080+
"docstring-format-checker": {
1081+
"$ref": "https://json.schemastore.org/partial-dfc.json",
1082+
"title": "docstring-format-checker",
1083+
"description": "A CLI tool to check and validate Python docstring formatting and completeness"
10741084
}
10751085
},
10761086
"examples": [

‎src/test/pyproject/dfc.toml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#:schema ../../schemas/json/pyproject.json
2+
[tool.dfc]
3+
allow_undefined_sections = true
4+
require_docstrings = true
5+
check_private = false
6+
validate_param_types = true
7+
optional_style = "validate"
8+
9+
[[tool.dfc.sections]]
10+
name = "Args"
11+
type = "list_name_and_type"
12+
order = 1
13+
admonition = false
14+
required = true
15+
16+
[[tool.dfc.sections]]
17+
name = "Returns"
18+
type = "list_type"
19+
order = 2
20+
admonition = "note"
21+
prefix = "Return value:"
22+
required = false
23+
message = "Missing returns section"
24+
25+
[[tool.dfc.sections]]
26+
name = "Raises"
27+
type = "list_name"
28+
order = 3
29+
required = false
30+
31+
[[tool.dfc.sections]]
32+
name = "Examples"
33+
type = "free_text"
34+
order = 4
35+
admonition = "example"
36+
required = false

‎src/test/pyproject/docstring-format-checker.toml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
#:schema ../../schemas/json/pyproject.json
2+
[tool.docstring-format-checker]
3+
allow_undefined_sections = false
4+
require_docstrings = true
5+
check_private = true
6+
validate_param_types = true
7+
optional_style = "strict"
8+
9+
[[tool.docstring-format-checker.sections]]
10+
name = "Parameters"
11+
type = "list_name_and_type"
12+
order = 1
13+
required = true
14+
admonition = false
15+
16+
[[tool.docstring-format-checker.sections]]
17+
name = "Returns"
18+
type = "list_type"
19+
order = 2
20+
required = true
21+
admonition = "info"
22+
prefix = "Returns:"
23+
message = "Return type documentation is required"
24+
25+
[[tool.docstring-format-checker.sections]]
26+
name = "Raises"
27+
type = "list_name"
28+
order = 3
29+
required = false
30+
31+
[[tool.docstring-format-checker.sections]]
32+
name = "Yields"
33+
type = "list_type"
34+
order = 4
35+
required = false
36+
37+
[[tool.docstring-format-checker.sections]]
38+
name = "Note"
39+
type = "free_text"
40+
admonition = "note"
41+
required = false

0 commit comments

Comments
 (0)
⚡