From 672ceb9d510a7fb322eb4384654a961c9de1fd6c Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 2 Jul 2024 16:59:17 -0400 Subject: [PATCH 1/2] Function signatures should use slash/star as needed --- documentation/style-guide.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index e28691e10e..35b23afbbd 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -291,3 +291,13 @@ 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 docs: + +- 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): From da1b11ae0706c7b7234cf0a63ee024374c3d8b66 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Thu, 11 Jul 2024 16:31:21 -0400 Subject: [PATCH 2/2] explain more about the reason to use slash/star --- documentation/style-guide.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 35b23afbbd..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 ======== @@ -295,9 +296,14 @@ 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 docs: +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.