llvm dev - Aug 2020 - 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.

----------------------------------------------------------------
Windfall               Paul C. Anagnostopoulos 
      ----------------------------------------------------------
   Software            978 369-0839
                             www.windfall.com
----------------------------------------------------------------
My life has been filled with calamities,
some of which actually happened.
---Mark Twain 

Guga 'mzimba, sala 'nhliziyo

Am Fr., 14. Aug. 2020 um 11:24 Uhr schrieb Paul C. Anagnostopoulos via
llvm-dev <llvm-dev at lists.llvm.org>:
> :doc:`Title <TableGen/ProgRef>`
>
A link to another document with a path relative to the current document.
Title is the <a href="...">caption</a> 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/...>`_
>
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200814/1bbc5ffc/attachment.html>