diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index e28691e10e..af5c88860f 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -99,6 +99,7 @@ such as "for example" or "that is." .. index:: diataxis +.. _diataxis: Diátaxis ======== @@ -291,3 +292,18 @@ errors ("I made a mistake, therefore the docs must be wrong ..."). Typically, the documentation wasn't consulted until after the error was made. It is unfortunate, but typically no documentation edit would have saved the user from making false assumptions about the language ("I was surprised by ..."). + +Function signatures +=================== + +These are the evolving guidelines for how to include function signatures in the +reference guide. As outlined in :ref:`diataxis`, reference material should +prioritize precision and completeness. + +- If a function accepts positional-only or keyword-only arguments, include the + slash and the star in the signature as appropriate:: + + .. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2): + + Although the syntax is terse, it is precise about the allowable ways to call + the function and is taken from Python itself.