Docs: improve format of rst links (to aid translation)

[odscrachel]

When representing rst links, the UI is inconsistent in Transifex with some showing as :rolename:`description <link>` and some shown as :rolename:`description` with a grey flag in place of the <link>. This creates some confusion for translators and hard to describe in the guidance. The UI issue is probably to do with :doc:, :any: and :ref: roles being handled differently in Transifex.

To avoid this is future (and to make translation easier) we could edit the docs to use :ref:`link` instead of custom text like :ref:`Custom text <link>`.

[kd-ods]

There is an additional issue with embedded links. On the credits.rst page for BODS 0.4 there has been an issue where translated strings in po files have not been picked up and inserted as expected in the sphinx-build process. (And no build warning flags that this is the case. The only way of spotting the issue is by seeing on the built page that there are English strings amongst the Spanish or French.) An example of a po file entry that causes this issue is:

#: ../../about/credits.rst:4 c2ea99c5ce6348c9b1f565cb6659f0b1
msgid ""
"The beta version of the Beneficial Ownership Data Standard was written by "
"Tim Davies (`Open Data Services <https://www.opendataservices.coop>`_) with "
"Ben Symonds (`OpenCorporates <https://www.opencorporates.com>`_), Chris "
"Taggart (`OpenCorporates <https://www.opencorporates.com>`_) and Jack Lord "
"(`Open Data Services <https://www.opendataservices.coop>`_) and input from "
"the :doc:`data standard working group <governance>`."
msgstr ""
"La versión beta del Estándar de datos sobre titularidad del beneficiario "
"real fue desarrollada por Tim Davies (`Open Data Services "
"<https://www.opendataservices.coop>`_) con Ben Symonds (`OpenCorporates "
"<https://www.opencorporates.com>`_), Chris Taggart (`OpenCorporates "
"<https://www.opencorporates.com>`_) y Jack Lord (`Open Data Services "
"<https://www.opendataservices.coop>`_), y con aportes del :doc:`grupo de "
"trabajo sobre estándares de datos <governance>`."

On investigation, it looks like the problem is the embedded uri named links are duplicated. That is, there are multiple instances of, for example:

(`Open Data Services <https://www.opendataservices.coop>`_ 

From the rst docs:

With a single trailing underscore, the reference is named -- the reference name should be unique and may be referred to again. With two trailing underscores, the reference and target are both anonymous and the target cannot be referred to again.

Although this doesn't seem to cause issues in the source build (ie. the issue is present in the msgid above), the multiple instances of named references in the msgstr seems to cause translation builds to quietly fail and fall back to including the original English string.

The solution is to etiher:

• use double underscores across the docs for external urls, or
• use single underscores carefully, ensuing that reference name is unique

The first is probably preferable. And we should explain the choice in the style guide.