chore(python): check OPTIONS.rst freshness
What changed, and why it matters
This commit adds a build-time check to ensure that a documentation file (OPTIONS.rst) for the trezorctl command-line tool is up to date. It does not change any security-sensitive code, cryptography, device firmware, or user-facing behavior. It is purely a developer tooling and documentation freshness check.
No security action required. This is a routine developer-experience/documentation maintenance change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch extends the Makefile’s ‘gen’ and ‘gen_check’ targets to include a new ‘python_doc’/’python_doc_check’ target. It modifies python/helper-scripts/make-options-rst.py to support a –check mode that compares the generated OPTIONS.rst content against the committed file without writing changes. No runtime, firmware, or cryptographic code is touched.
Changed components
python/helper-scripts/make-options-rst.pypython/MakefileMakefileInspect captured patch +38 / −11
diff --git a/Makefile b/Makefile
index c6086f4f..b91ccf34 100644
--- a/Makefile
+++ b/Makefile
@@ -22,6 +22,7 @@
hsm_keys hsm_keys_check \
prodtest_error_codes prodtest_error_codes_check \
certs certs_check \
+ python_doc python_doc_check \
gen gen_check \
uvlock_check
@@ -240,9 +241,15 @@ certs:
certs_check:
./core/tools/generate_certificates.py --check
-gen: templates mocks icons protobuf vendorheader solana_templates bootloader_hashes lsgen tropic_config hsm_keys prodtest_error_codes certs ## regenerate auto-generated files from sources
+python_doc: ## generate trezorctl OPTIONS.rst
+ make -C python doc
-gen_check: templates_check mocks_check icons_check protobuf_check vendorheader_check solana_templates_check bootloader_hashes_check lsgen_check tropic_config_check hsm_keys_check prodtest_error_codes_check certs_check ## check validity of auto-generated files
+python_doc_check: ## check that trezorctl OPTIONS.rst is up to date
+ make -C python doc_check
+
+gen: templates mocks icons protobuf vendorheader solana_templates bootloader_hashes lsgen tropic_config hsm_keys prodtest_error_codes certs python_doc ## regenerate auto-generated files from sources
+
+gen_check: templates_check mocks_check icons_check protobuf_check vendorheader_check solana_templates_check bootloader_hashes_check lsgen_check tropic_config_check hsm_keys_check prodtest_error_codes_check certs_check python_doc_check ## check validity of auto-generated files
uvlock_check: ## check that uv.lock is up to date
@echo [UVLOCK-CHECK]
diff --git a/python/Makefile b/python/Makefile
index 9e94d525..705a897b 100644
--- a/python/Makefile
+++ b/python/Makefile
@@ -13,6 +13,9 @@ dist: doc clean
doc:
$(PYTHON) helper-scripts/make-options-rst.py
+doc_check:
+ $(PYTHON) helper-scripts/make-options-rst.py --check
+
clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
clean-build: ## remove build artifacts
@@ -54,7 +57,7 @@ style_quick_check:
black --check $(BLACK_FLAGS) $(STYLE_TARGETS)
isort --check-only $(STYLE_TARGETS)
-.PHONY: all build install clean style style_check git-clean clean-build clean-pyc clean-test
+.PHONY: all build install clean doc doc_check style style_check git-clean clean-build clean-pyc clean-test
test:
pytest tests
diff --git a/python/helper-scripts/make-options-rst.py b/python/helper-scripts/make-options-rst.py
index e0b68deb..ecdc4dfb 100755
--- a/python/helper-scripts/make-options-rst.py
+++ b/python/helper-scripts/make-options-rst.py
@@ -16,7 +16,10 @@
# You should have received a copy of the License along with this library.
# If not, see <https://www.gnu.org/licenses/lgpl-3.0.html>.
-import os
+import argparse
+import sys
+from io import StringIO
+from pathlib import Path
from typing import List
import click
@@ -24,25 +27,30 @@ import click
from trezorlib.cli import trezorctl
DELIMITER_STR = "### ALL CONTENT BELOW IS GENERATED"
+OPTIONS_RST = Path(__file__).resolve().parent.parent / "docs" / "OPTIONS.rst"
-options_rst = open(os.path.dirname(__file__) + "/../docs/OPTIONS.rst", "r+")
+parser = argparse.ArgumentParser()
+parser.add_argument(
+ "--check", action="store_true", help="only verify that OPTIONS.rst is up to date"
+)
+args = parser.parse_args()
+
+current = OPTIONS_RST.read_text()
+output = StringIO()
lead_in: List[str] = []
-for line in options_rst:
+for line in current.splitlines(keepends=True):
lead_in.append(line)
if DELIMITER_STR in line:
break
-options_rst.seek(0)
-options_rst.truncate(0)
-
for line in lead_in:
- options_rst.write(line)
+ output.write(line)
def _print(s: str = "") -> None:
- options_rst.write(s + "\n")
+ output.write(s + "\n")
def rst_code_block(help_str: str) -> None:
@@ -68,3 +76,12 @@ for subcommand in sorted(trezorctl.cli.commands):
rst_code_block(f"trezorctl {subcommand} --help")
ctx = click.Context(cmd, info_name=f"trezorctl {subcommand}", terminal_width=99)
rst_code_block(cmd.get_help(ctx))
+
+generated = output.getvalue()
+
+if args.check:
+ if current != generated:
+ sys.exit(f"{OPTIONS_RST.name} is out of date, run `make python_doc` to fix")
+elif current != generated:
+ OPTIONS_RST.write_text(generated)
+ print(f"regenerated {OPTIONS_RST.name}")
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.