document how to use :doc: directive

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

(From yocto-docs rev: 2729250bf1068814e5106d1e71796e8a505963d7)

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 20 insertions, 1 deletions

diff --git a/documentation/README b/documentation/README
index 02037e0f7e..56eac7ca19 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 8300d813dc..801efe3457 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