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