diff mbox series

[2/2] document how to use :doc: directive

Message ID 20250618-doc-abs-path-v1-2-9f62e0ac92d2@cherry.de
State Under Review
Headers show
Series be consistent across all local :doc: references | expand

Commit Message

Quentin Schulz June 18, 2025, 3:13 p.m. UTC 
From: Quentin Schulz <quentin.schulz@cherry.de>

Let's specify that we are only expecting "absolute" paths in the docs
directive for local document referencing.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 documentation/README       | 10 ++++++++++
 documentation/standards.md | 11 ++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)
diff mbox series

Patch

diff --git a/documentation/README b/documentation/README
index 02037e0f7ecf5c7ea18688e8ffbcfbd60c859f1c..56eac7ca1953a3b001daaba18ac7f63305c94b68 100644
--- a/documentation/README
+++ b/documentation/README
@@ -314,6 +314,16 @@  See https://stackoverflow.com/questions/27420317/restructured-text-rst-http-link
 Anchor (<#link>) links are forbidden as they are not checked by Sphinx during
 the build and may be broken without knowing about it.
 
+It is also possible to refer to another document within yocto-docs with the
+:doc: directive (c.f.
+https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc), e.g.:
+
+  For more information, read :doc:`/bsp-guide/index`.
+
+Note that only "absolute" paths (starting with a '/') are allowed. The root
+directory of that path is documentation/, that is, :doc:`/bsp-guide/index`
+points at documentation/bsp-guide/index.rst.
+
 References
 ==========
 
diff --git a/documentation/standards.md b/documentation/standards.md
index 8300d813dccba87a4d235a43b2ea7a414042e9bc..801efe3457aa9c8e7175ab15c25abbf0789df8e0 100644
--- a/documentation/standards.md
+++ b/documentation/standards.md
@@ -126,7 +126,16 @@  that most themes only style these two admonitions.
 
 ## ReStructured Text Syntax standards
 
-This section has not been filled yet
+### doc directive
+
+The [doc directive](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc)
+allows to refer to another document within yocto-docs, like:
+
+    For more information, read :doc:`/bsp-guide/index`.
+
+Note that only "absolute" paths (starting with a '/') are allowed. The root
+directory of that path is documentation/, that is, :doc:`/bsp-guide/index`
+points at documentation/bsp-guide/index.rst.
 
 ## Adding screenshots