p71924506
/
linux_old1
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Document cross-referencing using relative path 

Update the Cross-referencing section to explain how to create a
cross-reference to a document using relative paths and with no
additional syntax, by relying on automarkup.py.

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20210128010028.58541-3-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Nícolas F. R. A. Prado 2021-01-28 01:01:36 +00:00 committed by Jonathan Corbet
parent ea1d838980
commit 1e013ff7cb
1 changed files with 17 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
Documentation/doc-guide/sphinx.rst
View File

@ -340,16 +340,26 @@ Rendered as:
Cross-referencing
-----------------
Cross-referencing from one documentation page to another can be done by passing
the path to the file starting from the Documentation folder.
For example, to cross-reference to this page (the .rst extension is optional)::
Cross-referencing from one documentation page to another can be done simply by
writing the path to the document file, no special syntax required. The path can
be either absolute or relative. For absolute paths, start it with
"Documentation/". For example, to cross-reference to this page, all the
following are valid options, depending on the current document's directory (note
that the ``.rst`` extension is required)::
See Documentation/doc-guide/sphinx.rst.
See Documentation/doc-guide/sphinx.rst. This always works.
Take a look at sphinx.rst, which is at this same directory.
Read ../sphinx.rst, which is one directory above.
If you want to use a relative path, you need to use Sphinx's ``doc`` directive.
For example, referencing this page from the same directory would be done as::
If you want the link to have a different rendered text other than the document's
title, you need to use Sphinx's ``doc`` role. For example::
See :doc:`sphinx`.
See :doc:`my custom link text for document sphinx <sphinx>`.
For most use cases, the former is preferred, as it is cleaner and more suited
for people reading the source files. If you come across a ``:doc:`` usage that
isn't adding any value, please feel free to convert it to just the document
path.
For information on cross-referencing to kernel-doc functions or types, see
Documentation/doc-guide/kernel-doc.rst.