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 `_.
+
+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` 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/_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")