From 8a198b29f53a6d8d66ec40da818835184b93ecdc Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 13 Dec 2024 18:02:21 +0100 Subject: [PATCH 1/2] DOC: Enhance documentation on discouraged API The added recommendation is already in use in our codebase. Enhances #29078. Closes #19017. --- doc/devel/api_changes.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst index 09709b0ec580..c36b5f90cfde 100644 --- a/doc/devel/api_changes.rst +++ b/doc/devel/api_changes.rst @@ -256,3 +256,8 @@ To do so, add a note to the docstring :: You find several examples for good descriptions if you search the codebase for ``.. admonition:: Discouraged``. + +Additionally, if a whole function is discouraged, prefix the summary line with +``[*Discouraged*]`` so that it renders in API overview like this + + [*Discouraged*] Return the XAxis instance. From 399a473bb6540facfb76ec623e44c6b3b2befbe7 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 13 Dec 2024 19:20:49 +0100 Subject: [PATCH 2/2] Update doc/devel/api_changes.rst Co-authored-by: hannah --- doc/devel/api_changes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst index c36b5f90cfde..8b947ee946a7 100644 --- a/doc/devel/api_changes.rst +++ b/doc/devel/api_changes.rst @@ -258,6 +258,6 @@ You find several examples for good descriptions if you search the codebase for ``.. admonition:: Discouraged``. Additionally, if a whole function is discouraged, prefix the summary line with -``[*Discouraged*]`` so that it renders in API overview like this +``[*Discouraged*]`` so that it renders in the API overview like this [*Discouraged*] Return the XAxis instance.