http://docutils.sourceforge.net/docs/user/rst/quickref.html#external-hyperlink-targets shows this example:
External hyperlinks, like Python_.
.. _Python: http://www.python.org/
But http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#external-links shows this example:
This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/
I am trying to understand which of these two syntaxes are correct and work with all restructuredtext renderers.
Should I use:
Foo_
to refer to a hyperlink?
Or should I use:
`Foo`_
to refer to a hyperlink?
Both are correct. The syntax for a hyperlink is just an underscore _. Backticks are required when the name for the hyperlink contains spaces. Otherwise, both are acceptable. Technically speaking, the backticks are called a "grouping syntax".
It is common practice just to include backticks even if the name for the hyperlink doesn't contain spaces. This is because it's not always immediately understood whether a lone _ is a typo for a phrase that should containing an underscore or a hyperlink. The ``_ syntax, however, is known to be a hyperlink in reST.