From bb3fc03ef167a005cdf1192df60ac2fb1cbc5ae3 Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Thu, 27 Oct 2022 11:46:21 +0200 Subject: Documentation/README: formalize guidelines for external link syntax (From yocto-docs rev: f5d10ceed943270d7bcfa31b5936f37a60669c7f) Signed-off-by: Michael Opdenacker Signed-off-by: Richard Purdie --- documentation/README | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'documentation/README') diff --git a/documentation/README b/documentation/README index 6333f0496a..c27ed86a33 100644 --- a/documentation/README +++ b/documentation/README @@ -275,6 +275,19 @@ websites. More information can be found here: https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html. +For external links, we use this syntax: +`link text `__ + +instead of: +`link text `_ + +Both syntaxes work, but the latter also creates a "link text" reference +target which could conflict with other references with the same name. +So, only use this variant when you wish to make multiple references +to this link, reusing only the target name. + +See https://stackoverflow.com/questions/27420317/restructured-text-rst-http-links-underscore-vs-use + Anchor (<#link>) links are forbidden as they are not checked by Sphinx during the build and may be broken without knowing about it. -- cgit v1.2.3-54-g00ecf