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>

2 files changed, 43 insertions, 1 deletions

diff --git a/docs/differences/modules_preamble.txt b/docs/differences/modules_preamble.txt
new file mode 100644
index 000000000..1958f0084
--- /dev/null
+++ b/docs/differences/modules_preamble.txt
@@ -0,0 +1,33 @@
+.. Preamble section inserted into generated output
+
+Positional-only Parameters
+--------------------------
+
+To save code size, many functions that accept keyword arguments in CPython only accept positional arguments in MicroPython.
+
+MicroPython marks positional-only parameters in the same way as CPython, by inserting a ``/`` to mark the end of the positional parameters. Any function whose signature ends in ``/`` takes *only* positional arguments. For more details, see `PEP 570 <https://peps.python.org/pep-0570/>`_.
+
+Example
+~~~~~~~
+
+For example, in CPython 3.4 this is the signature of the constructor ``socket.socket``::
+
+    socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)
+
+However, the signature documented in :func:`MicroPython<socket.socket>` is::
+
+    socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP, /)
+
+The ``/`` at the end of the parameters indicates that they are all positional-only in MicroPython. The following code works in CPython but not in most MicroPython ports::
+
+    import socket
+    s = socket.socket(type=socket.SOCK_DGRAM)
+
+MicroPython will raise an exception::
+
+    TypeError: function doesn't take keyword arguments
+
+The following code will work in both CPython and MicroPython::
+
+    import socket
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
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")