External references in .rst documentation files

Could a reStructured text/Sphinx maven tell me the correct way to code an external reference in a documentation file? In one file I found three different methods:

:doc:`Title <TableGen/ProgRef>`

:doc:`../CodeGenerator`

`Title <https://clang.llvm.org/docs/…>`_

I had no luck searching online. If it matters, I'm adding cross-references between TableGen documents that are all in the same docs/ TableGen directory.

:doc:Title <TableGen/ProgRef>

A link to another document with a path relative to the current document. Title is the caption of the link.

:doc:../CodeGenerator

A link to another document with a path relative to the current document. The linked document’s title is used for the caption.

Title <[https://clang.llvm.org/docs/..](https://clang.llvm.org/docs/..).>_

A link to an arbitrary URL. Please avoid for cross-references as it should change relative to where the documents are. For instance, each the documentation of each release should link to the version of its release (e.g. https://releases.llvm.org/10.0.0/tools/clang/docs/index.html), not the latest from trunk (e.g. https://clang.llvm.org/docs/index.html)

I had no luck searching online. If it matters, I’m adding cross-references between TableGen documents that are all in the same docs/ TableGen directory.

reStructured Text documentation is available at:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks

https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-doc.

The :ref: role is useful as well.

Michael