1

Prefixing the link with an ! suppresses the creation of a reference (e.g. :ref:`!no link` will be simply rendered as no link):

If you prefix the content with !, no reference/hyperlink will be created.

However, I can't think of any practical usage of this. Why should I first create a reference and then don't want to use it - it would be far easier to write plain text from the very beginning.

So - what is a typical use case of such a suppressed reference?

(Sphinx itself for instance doesn't use it in its docs.)

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Stef
  • 28,728
  • 2
  • 24
  • 52

1 Answers1

1

I can't think of any practical usage of this.

The use I can think of is before a build if you wanted to "turn of" hyperlink generation for one given cross-reference (that appears multiple times) how would you do it?

Well, the simplest way might be using some text editor's "find and replace", and arguably the least invasive way would be to add or remove a single character !. That way the length and structure of the cross-reference is kept in the source (and the title is still rendered in place). This could be convenient in several places, like a table where removing the whole cross-reference could misalign the source.

The most economical change possible would be turning this:

:ref:`a very long title <an.extremely.long.link.target>`

into this:

:ref:`!a very long title <an.extremely.long.link.target>`

The same could possibly be achieved programmatically using the Sphinx API, but a lot of Sphinx users are likely to prefer a text editing solution over a programmatic one.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
  • 1
    So I get it'd be mainly a temporary solution, unlikely to be seen in the final version. This makes (some) sense. – Stef Sep 25 '22 at 20:22
  • 1
    @Stef [depending on style guide](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Linking#Duplicate_and_repeat_links) you may want to have cross-references with the same title leading to different targets. In that case, to avoid ambiguity, even if you only render some of them as links you may want to keep the link target in the source - if at some point you decide to refactor it'll make things easier. (This kind of functionality becomes more important the larger the codebase/documentation is.) – bad_coder Sep 26 '22 at 01:53
  • 1
    @Stef after further research I've found the behavior of the exclamation mark `!` is inconsistent compared to `~`. Apparently it's a legacy functionality from the earliest Sphinx versions that was never revised, here's the lead Sphinx dev asking the same question you've asked [issue #1474](https://github.com/sphinx-doc/sphinx/issues/1474) – bad_coder Sep 28 '22 at 08:20
  • I will revise my answer soon. – bad_coder Sep 28 '22 at 09:34