docs: Add note about position-only arguments in CPython vs MicroPython.

Required modifying the gen-cpydiff.py code to allow a "preamble" section to
be inserted at the top of any of the generated files.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>

1 files changed, 10 insertions, 1 deletions

diff --git a/tools/gen-cpydiff.py b/tools/gen-cpydiff.py
index 29545bad0..578b6c136 100644
--- a/tools/gen-cpydiff.py
+++ b/tools/gen-cpydiff.py
@@ -47,7 +47,8 @@ else:
 
 TESTPATH = "../tests/cpydiff"
 DOCPATH = "../docs/genrst"
-INDEXTEMPLATE = "../docs/differences/index_template.txt"
+SRCDIR = "../docs/differences"
+INDEXTEMPLATE = os.path.join(SRCDIR, "index_template.txt")
 INDEX = "index.rst"
 
 HEADER = ".. This document was generated by tools/gen-cpydiff.py\n\n"
@@ -219,6 +220,14 @@ def gen_rst(results):
                     rst.write(section[i] + "\n")
                     rst.write(RSTCHARS[0] * len(section[i]))
                     rst.write(time.strftime("\nGenerated %a %d %b %Y %X UTC\n\n", time.gmtime()))
+                    # If a file docs/differences/<filename>_preamble.txt exists
+                    # then its output is inserted after the top-level heading,
+                    # but before any of the generated sections.
+                    preamble_path = os.path.join(SRCDIR, filename + "_preamble.txt")
+                    if os.path.exists(preamble_path):
+                        with open(preamble_path, "r") as f:
+                            rst.write(f.read())
+                        rst.write("\n")
                     toctree.append(filename)
                 else:
                     rst.write(section[i] + "\n")