| name | usethis-qa-config-files-sync |
| description | Check whether docs/config-files.txt (the machine-readable export) is in-sync with the per-tool tables in docs/about/config-files.md |
| compatibility | usethis, Python, markdown, documentation |
| license | MIT |
| metadata | {"version":"1.0"} |
Config Files Documentation Sync Check
The project maintains two representations of per-tool configuration file support:
docs/config-files.txt — a machine-readable export generated by the export-config-files prek hookdocs/about/config-files.md — the human-readable documentation page
The txt file is auto-generated from the Python API; the md page is hand-maintained. These can drift out of sync when tools are added, removed, or reconfigured.
Procedure
- Read
docs/config-files.txt. Each line has the form: Tool Name: file1, file2, ... (resolution=<mode>), or for tools with no resolution: Tool Name: file1, file2, ...
- Read
docs/about/config-files.md. For each tool, find the corresponding ### Tool Name section and extract the file names from the | File | Section | markdown table.
- For each tool in
config-files.txt, verify:
- A matching
### Tool Name section exists in config-files.md.
- The files listed in
config-files.txt (in order) match the file column entries in the markdown table (in order).
- Report any discrepancies: missing sections, extra sections, or file lists that differ in membership or order.
- Fix any gaps found by updating
docs/about/config-files.md to match docs/config-files.txt.
What counts as a discrepancy
- A tool present in
config-files.txt but missing a ### Tool Name section in config-files.md.
- A tool with a
### Tool Name section in config-files.md that is not present in config-files.txt.
- A file listed for a tool in
config-files.txt that does not appear in the corresponding markdown table.
- A file in the markdown table that does not appear in
config-files.txt for that tool.
- Files present in both but listed in a different order.
Authoritative source
docs/config-files.txt is the authoritative source — it is generated directly from the Python API via the export-config-files prek hook. When a discrepancy exists, update docs/about/config-files.md to match it, not the other way around.
The resolution mode (e.g. resolution=first, resolution=first_content) in config-files.txt provides context for any callout notes in config-files.md; it does not have a required structural equivalent in the markdown table.
