From 87ec4869628d39ee2ba56c5ddb6e0b8349556aaf Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 21 Jul 2025 10:36:18 +1200
Subject: [PATCH] docs/internal: Add note on synth_* script highlighting

---
 docs/source/cmd/index_internal.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/source/cmd/index_internal.rst b/docs/source/cmd/index_internal.rst
index a077dc2a4..dc9980171 100644
--- a/docs/source/cmd/index_internal.rst
+++ b/docs/source/cmd/index_internal.rst
@@ -101,6 +101,15 @@ Dumping command help to json
    :end-before: "chparam": {
    :caption: `chformal` in generated :file:`cmds.json`
 
+.. note:: Synthesis command scripts are special cased
+
+   If the final block of help output starts with the string `"The following
+   commands are executed by this synthesis command:\n"`, then the rest of the
+   code block is formatted as ``yoscrypt`` (e.g. `synth_ice40`).  The caveat
+   here is that if the ``script()`` calls ``run()`` on any commands *prior* to
+   the first ``check_label`` then the auto detection will break and revert to
+   unformatted code (e.g. `synth_fabulous`). 
+
 Command line rendering
 ~~~~~~~~~~~~~~~~~~~~~~