You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The validation of `pyproject.toml` files in modern IDEs relies on a sophisticated ecosystem of standards and community-driven repositories. Utilise JSON Schema to ensure that configuration errors are caught during authoring rather than at runtime.
7
+
8
+
When you open a `pyproject.toml` file in VS Code with the `Even Better TOML` extension, several processes occur:
9
+
10
+
1.**Schema Association**: Check if there is a mapping between the filename and a known schema. For common files like `pyproject.toml`, this mapping is often retrieved from a central registry.
11
+
2.**SchemaStore.org**: Fetch schemas from this source automatically via extensions. This is the primary open-source repository where most schemas for configuration files live.
12
+
3.**JSON Schema Standard**: Convert the TOML data into a JSON-compatible structure and validate it against the rules defined in the schema.
13
+
14
+
15
+
## 🛠️ Schema Generation
16
+
17
+
To support `[tool.dfc]` in the `pyproject.toml` file, a JSON Schema fragment is required that describes the configuration structure. This project uses a tailored script to automate this process.
18
+
19
+
20
+
### ⚙️ Automated Generation
21
+
22
+
Utilise the [src/utils/generate_config_schema.py](../../utils/generate_config_schema.py) script to generate and update the schema files. This script uses introspection on the `GlobalConfig()` and `SectionConfig()` classes to ensure the schema always reflects the actual code structure.
23
+
24
+
Run the following command to regenerate the schemas:
25
+
26
+
```bash
27
+
source .venv/bin/activate
28
+
uv run ./src/utils/generate_config_schema.py
29
+
```
30
+
31
+
32
+
### 🚀 Continuous Integration
33
+
34
+
This generation process is integrated into the project's CI workflow, as defined in [.github/workflows/ci.yml](.github/workflows/ci.yml). During a pull request, the CI environment executes the generator and validates that no drift has occurred between the code and the schema files:
35
+
36
+
- Execute `uv run ./src/utils/generate_config_schema.py` to generate the latest schemas.
37
+
- Run `git diff --exit-code src/schemas/json/` to ensure that any changes to the configuration classes have been correctly captured and committed in the schema.
38
+
39
+
40
+
## 📜 Generated Schema Files
41
+
42
+
Two primary schema files are generated in this directory:
43
+
44
+
-[partial-dfc.json](partial-dfc.json): Contains the core schema definitions for the `dfc` tool configuration. This is the file intended for submission to SchemaStore.org.
45
+
-[pyproject.json](pyproject.json): A wrapper schema used for local testing and validation of the entire `pyproject.toml` structure.
46
+
47
+
48
+
### 💻 Local Validation in VS Code
49
+
50
+
Before a schema is merged into the global SchemaStore registry, you can test validation locally in your workspace. Add the following to your `settings.json` to associate the local schema with your `pyproject.toml`:
"$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": [
37
+
"silent",
38
+
"validate",
39
+
"strict"
40
+
],
41
+
"default": "validate"
42
+
},
43
+
"sections": {
44
+
"type": "array",
45
+
"title": "Docstring Sections",
46
+
"description": "List of docstring section configurations.",
47
+
"items": {
48
+
"type": "object",
49
+
"additionalProperties": false,
50
+
"required": [
51
+
"name",
52
+
"type"
53
+
],
54
+
"properties": {
55
+
"name": {
56
+
"title": "Name",
57
+
"description": "Name of the docstring section.",
58
+
"type": "string"
59
+
},
60
+
"type": {
61
+
"title": "Type",
62
+
"description": "Type of the section content.",
63
+
"type": "string",
64
+
"enum": [
65
+
"free_text",
66
+
"list_name",
67
+
"list_type",
68
+
"list_name_and_type"
69
+
]
70
+
},
71
+
"order": {
72
+
"title": "Order",
73
+
"description": "Order of the section in the docstring.",
74
+
"type": [
75
+
"integer",
76
+
"null"
77
+
],
78
+
"default": null
79
+
},
80
+
"admonition": {
81
+
"title": "Admonition",
82
+
"description": "Admonition style for the section. Can be False (no admonition) or a string specifying the admonition type.",
83
+
"type": [
84
+
"boolean",
85
+
"string"
86
+
],
87
+
"default": false
88
+
},
89
+
"prefix": {
90
+
"title": "Prefix",
91
+
"description": "Prefix string for the admonition values.",
92
+
"type": "string",
93
+
"default": ""
94
+
},
95
+
"required": {
96
+
"title": "Required",
97
+
"description": "Whether this section is required in the docstring.",
98
+
"type": "boolean",
99
+
"default": false
100
+
},
101
+
"message": {
102
+
"title": "Message",
103
+
"description": "Optional message for validation errors.",
0 commit comments