From 76f269116023c7f6c12a9297b294a73e9414bfc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Tue, 27 May 2025 13:22:08 -0300 Subject: [PATCH 1/3] Document autolink role for autosummary --- doc/usage/extensions/autosummary.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 456faee1830..e6945b06587 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -412,3 +412,10 @@ the title of a page. Stub pages are generated also based on these directives. .. _`escape filter`: https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.escape + +Autolink role +------------- + +The ``:autolink:`` role functions as ``:obj:`` when the name referred can be +resolved to a Python object, and otherwise it becomes simple emphasis. +This can be used as the default role to make links 'smart'. From 17ffa223b2bf2c315fa3cd86da20bb1aa4ff8e47 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sat, 7 Jun 2025 17:13:08 +0100 Subject: [PATCH 2/3] Update doc/usage/extensions/autosummary.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Melissa Weber Mendonça --- doc/usage/extensions/autosummary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index e6945b06587..00963344463 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -418,4 +418,4 @@ Autolink role The ``:autolink:`` role functions as ``:obj:`` when the name referred can be resolved to a Python object, and otherwise it becomes simple emphasis. -This can be used as the default role to make links 'smart'. +This can be used as the default role to make links 'smart', but must be used carefully. For example, in the case of multiple objects having the same name, `autolink` could resolve to the wrong object. From 2a63b9d5be9601be4dc0b13d4fdf0dce4be4dd9b Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sat, 7 Jun 2025 17:23:45 +0100 Subject: [PATCH 3/3] expand --- doc/usage/extensions/autosummary.rst | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 00963344463..c84dcb60eff 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -416,6 +416,23 @@ the title of a page. Autolink role ------------- -The ``:autolink:`` role functions as ``:obj:`` when the name referred can be -resolved to a Python object, and otherwise it becomes simple emphasis. -This can be used as the default role to make links 'smart', but must be used carefully. For example, in the case of multiple objects having the same name, `autolink` could resolve to the wrong object. +.. rst:role:: autolink + + The ``:autolink:`` role functions as ``:py:obj:`` when the referenced *name* + can be resolved to a Python object, and otherwise it becomes simple emphasis. + + There are some known design flaws. + For example, in the case of multiple objects having the same name, + :rst:role:`!autolink` could resolve to the wrong object. + It will fail silently if the referenced object is not found, + for example due to a spelling mistake or renaming. + This is sometimes unwanted behaviour. + + Some users choose to configure their :confval:`default_role` to ``autolink`` + for 'smart' referencing using the default interpreted text role (```content```). + + .. seealso:: + + :rst:role:`any` + + :rst:role:`py:obj`