From e60c9d753cd7cda3df1492cee949a88c7713fb9b Mon Sep 17 00:00:00 2001 From: Quentin Schulz Date: Wed, 18 Jun 2025 17:13:36 +0200 Subject: [PATCH] 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 Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/README | 10 ++++++++++ documentation/standards.md | 11 ++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) 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