marlinfirmware/marlindocumentation/regenerate-settings

Regenerate the Settings reference

docs/settings/<section>.md pages are generated by _tools/gen_settings.py from the output of Marlin's buildroot/share/PlatformIO/scripts/schema.py. The generator owns the option entries; it keeps the human-owned fields (brief, long, since, example, see) and the markdown body of each page.

Steps

1. Commit the docs tree first so a bad run is easy to diff and revert.
2. Make a clean schema from upstream without touching a working checkout:

``sh mkdir -p ~/tmp/schema && cd ~/tmp/schema git -C <Marlin> archive upstream/bugfix-2.1.x Marlin | tar -x python3 <Marlin>/buildroot/share/PlatformIO/scripts/schema.py jsons # writes schema.json, schema_grouped.json ``

1. Snapshot the current pages so curated text can follow options that move between sections:

``sh cp -R docs/settings ~/tmp/settings-prior ``

1. Regenerate every section, always with --prior:

``sh for s in $(python3 -c "import json;print(' '.join(json.load(open('$HOME/tmp/schema/schema_grouped.json')).keys()))"); do python3 _tools/gen_settings.py --schema ~/tmp/schema/schema_grouped.json --section $s --prior ~/tmp/settings-prior done ` The report lists options added, dropped (gone from the firmware) and grouped. A "dropped" count after a grouping change can mean singles were folded into a numbered group (FIL_RUNOUT1_STATE`), not lost.

1. New sections need a title in TITLES in gen_settings.py (acronyms: LCD, TMC, PSU, IDEX) and show up as new

pages; they belong in the same commit, as does any change to _data/thermistors.yml.

1. Audit curated text: compare brief/long/since/example/see per option between git show HEAD:docs/settings/...

and the new pages. Expect zero losses except options removed from the firmware.

1. Build and check links. _data/setting_pages.yml is rebuilt from the pages on disk, so links to moved options

re-point themselves; check_links.py reports any that didn't. ``sh python3 _tools/check_site.py && bundle exec jekyll build && python3 _tools/check_links.py && python3 _tools/check_feed.py ``

1. Regenerate the obsolete-options list in the same pass, so renamed options get their "Formerly" line and

retired names keep resolving: ``sh python3 _tools/gen_obsolete.py --marlin <firmware checkout> [--abm <AutoBuildMarlin checkout>] ` It parses Marlin/src/inc/Changes.h into _data/obsolete.yml (+ obsolete_by_new.yml), merging the rename tables of Auto Build Marlin's abm/migration-rules.js (--abm, default $MARLIN_ABM) for names Changes.h never checked (board renames, removals) and replacements its messages do not name. The two sources agree on versions; until always comes from the tag scan. The "until" version of each name is the last upstream release tag whose config files still had it (tags are read from the upstream remote, so a stale local tag cannot leak in). Known versions are cached; only new names scan the tags. Rendered by docs/appendix/obsolete_options.md, the "Formerly" line in _layouts/setting.html, the setting_links` fallback (an obsolete name in backticks links to the appendix with a strikethrough) and the search index. A strikethrough link on a feature or settings page means the prose uses a retired name: fix the prose.

1. Commit the regeneration on its own, separate from prose edits.

Pitfalls

• Without --prior, curated text on options that changed section is silently lost.
• --prior covers top-level entries, not members inside a group.
• Never git checkout -- docs/settings/x.md to "reset" a page; the tree usually carries uncommitted prose.

Copy or diff instead.

• Option renames in the firmware (listed in Marlin/src/inc/Changes.h) leave stale names in prose, the kinematics

table (docs/settings/kinematics.md body) and KINEMATICS in _tools/gen_printers.py; grep for the old name.

• schema.py needs two local changes that are not yet upstream (block_clause for #else branches,

shared_comment for comment runs). If the upstream script lacks them, the requires and comment fields regress.