ci: check OPTIONS.rst freshness

Makefile

@@ -169,6 +169,12 @@ docs_summary_check: ## check if there are unlinked documentation files
 	@echo [DOCS-SUMMARY-MARKDOWN-CHECK]
 	python3 tools/check_docs_summary.py
 
+python_doc: ## generate trezorctl OPTIONS.rst
+	make -C python doc
+
+python_doc_check: ## check that trezorctl OPTIONS.rst is up to date
+	make -C python doc_check
+
 vendorheader: ## generate vendor header
 	./core/tools/generate_vendorheader.sh --quiet
 
@@ -199,9 +205,9 @@ hsm_keys:
 hsm_keys_check:
 	./core/tools/generate_hsm_keys.py --check
 
-gen:  templates mocks icons protobuf vendorheader solana_templates bootloader_hashes lsgen tropic_model_config hsm_keys ## regenerate auto-generated files from sources
+gen:  templates mocks icons protobuf python_doc vendorheader solana_templates bootloader_hashes lsgen tropic_model_config hsm_keys ## 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_model_config_check hsm_keys_check ## check validity of auto-generated files
+gen_check: templates_check mocks_check icons_check protobuf_check python_doc_check vendorheader_check solana_templates_check bootloader_hashes_check lsgen_check tropic_model_config_check hsm_keys_check ## check validity of auto-generated files
 
 uvlock_check: ## check that uv.lock is up to date
 	@echo [UVLOCK-CHECK]

python/Makefile

@@ -13,6 +13,14 @@ dist: doc clean
 doc:
 	$(PYTHON) helper-scripts/make-options-rst.py
 
+doc_check:
+	@echo [OPTIONS-RST-CHECK]
+	@set -e; \
+		tmp=$$(mktemp); \
+		trap 'rm -f "$$tmp"' EXIT; \
+		$(PYTHON) helper-scripts/make-options-rst.py --output "$$tmp"; \
+		diff -u docs/OPTIONS.rst "$$tmp"
+
 clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
 
 clean-build: ## remove build artifacts

python/docs/OPTIONS.rst

@@ -197,6 +197,7 @@ Miscellaneous debug features.
     optiga-set-sec-max  Set Optiga's security event counter to maximum.
     prodtest-t1         Perform a prodtest on Model One.
     record              Record screen changes into a specified directory.
+    set-battery-state   Set emulated battery/power state (emulator only).
     set-log-filter      Set logging filter string.
 
 Device management commands - setup, recover seed, wipe, etc.
@@ -312,6 +313,7 @@ Evolu commands.
   Commands:
     get-delegated-identity-key  Request the delegated identity key of this device.
     get-node                    Return the SLIP-21 node for Evolu.
+    index-management            Set the optional delegated identity key rotation index if unset.
     sign-registration-request   Sign a registration request for this device to be registered at...
 
 FIDO2, U2F and WebAuthN management commands.

python/helper-scripts/make-options-rst.py

@@ -16,33 +16,43 @@
 # 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
-from typing import List
+import argparse
+from pathlib import Path
+from typing import TextIO
 
 import click
 
 from trezorlib.cli import trezorctl
 
 DELIMITER_STR = "### ALL CONTENT BELOW IS GENERATED"
+OPTIONS_RST = Path(__file__).resolve().parent / "../docs/OPTIONS.rst"
 
-options_rst = open(os.path.dirname(__file__) + "/../docs/OPTIONS.rst", "r+")
+parser = argparse.ArgumentParser()
+parser.add_argument(
+    "--output",
+    type=Path,
+    default=OPTIONS_RST,
+    help="Path to write the generated OPTIONS.rst content.",
+)
+args = parser.parse_args()
 
-lead_in: List[str] = []
+lead_in: list[str] = []
 
-for line in options_rst:
-    lead_in.append(line)
-    if DELIMITER_STR in line:
-        break
+with OPTIONS_RST.open() as options_rst:
+    for line in options_rst:
+        lead_in.append(line)
+        if DELIMITER_STR in line:
+            break
 
-options_rst.seek(0)
-options_rst.truncate(0)
+output: TextIO
+output = args.output.open("w")
 
 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 +78,5 @@ def rst_code_block(help_str: str) -> None:
     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))
+
+output.close()

python/src/trezorlib/cli/evolu.py

@@ -114,6 +114,10 @@ def index_management(
     session: Session,
     rotation_index: Optional[int] = None,
 ) -> str:
+    """
+    Set the optional delegated identity key rotation index if unset.
+    Use --rotation_index to provide the value; returns the current index as a string.
+    """
     return str(
         evolu.index_management(
             session,