From 9062e849b89affdf3d2413c9dcdc6d0101b45c60 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Mar 2022 11:40:36 -0500 Subject: [PATCH 1/6] DOC: include keyword-only parameters in standard --- doc/format.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/format.rst b/doc/format.rst index 56e4a4f3..94206ed7 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -211,6 +211,10 @@ used as a value, ``optional`` is preferred. These are all equivalent:: copy : bool, default=True copy : bool, default: True +For keyword-only arguments, use ``keyword-only``:: + + x : int, keyword-only + When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:: From a28dd353560f724d3dcb7bdc40b9ee1f321fd0ba Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Mar 2022 12:21:37 -0500 Subject: [PATCH 2/6] DOC: add example combining keyword-only & optional --- doc/format.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/format.rst b/doc/format.rst index 94206ed7..291e1a83 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -214,6 +214,7 @@ used as a value, ``optional`` is preferred. These are all equivalent:: For keyword-only arguments, use ``keyword-only``:: x : int, keyword-only + y : int, keyword-only, optional When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:: From c8b05420852fb03f7448f393eca2c86659a518c3 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Mar 2022 12:50:41 -0500 Subject: [PATCH 3/6] DOC: include positional-only parameters in standard --- doc/format.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index 291e1a83..6a70de29 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -211,9 +211,10 @@ used as a value, ``optional`` is preferred. These are all equivalent:: copy : bool, default=True copy : bool, default: True -For keyword-only arguments, use ``keyword-only``:: +Use ``positional-only`` for positional-only parameters, and ``keyword-only`` +for keyword-only parameters:: - x : int, keyword-only + x : int, positional-only y : int, keyword-only, optional When a parameter can only assume one of a fixed set of values, From 6b65b19a76d3658f5af21be4a3d8cdc22e9b3c4c Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 2 Mar 2022 13:32:15 -0500 Subject: [PATCH 4/6] DOC: add example for keyword-only parameter --- doc/format.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/format.rst b/doc/format.rst index 6a70de29..c263b9fc 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -215,7 +215,8 @@ Use ``positional-only`` for positional-only parameters, and ``keyword-only`` for keyword-only parameters:: x : int, positional-only - y : int, keyword-only, optional + y : int, keyword-only + z : int, keyword-only, optional When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:: From 461eec42edb8f1a8eb443d74da17c7c86ae39cec Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Mon, 9 May 2022 20:23:32 -0400 Subject: [PATCH 5/6] Expand numpydoc_xref_ignore in install.rst --- doc/install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/install.rst b/doc/install.rst index e4ecd643..fb1a8786 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -86,7 +86,7 @@ numpydoc_xref_ignore : set or ``"all"`` used in parameter type descriptions that may be confused for classes of the same name. For example:: - numpydoc_xref_ignore = {'type', 'optional', 'default'} + numpydoc_xref_ignore = {'type', 'optional', 'default', 'keyword-only', 'positional-only'} The default is an empty set. From ad070dab8d61d978fafa569f7e62aed69a365dfc Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Mon, 9 May 2022 20:23:45 -0400 Subject: [PATCH 6/6] Expand numpydoc_xref_ignore in doc/conf.py --- doc/conf.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index ad142da7..34a628b6 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -83,7 +83,14 @@ version = re.sub(r'(\d+\.\d+)\.\d+(.*)', r'\1\2', numpydoc.__version__) version = re.sub(r'(\.dev\d+).*?$', r'\1', version) numpydoc_xref_param_type = True -numpydoc_xref_ignore = {'optional', 'type_without_description', 'BadException'} +numpydoc_xref_ignore = { + 'optional', + 'type_without_description', + 'BadException', + 'keyword-only', + 'positional-only', +} + # Run docstring validation as part of build process numpydoc_validation_checks = {"all", "GL01", "SA04", "RT03"}