From b9f0fabff0343f9c0267e056f2cf20f02f1ed6e9 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 21 Mar 2025 10:28:48 +1300
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
 ~~~~~~~~~~~~~~~~~~~~~~