From 3c6d8c5c1b3ea0f98d373ed99ec4bfb16561fb68 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Wed, 21 May 2025 11:32:11 -0600 Subject: [PATCH 1/3] docs(referencing.rst): add additional data about :doc: role --- doc/usage/referencing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 2597c9ce597..921c2c948b3 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -145,6 +145,9 @@ There is also a way to directly link to documents: If no explicit link text is given (like usual: ``:doc:`Monty Python members ```), the link caption will be the title of the given document. + Note that the string inside the single quotes must be a case-sensitive with + the file name, even on Windows. + Referencing downloadable files ------------------------------ From be1f9bea9400e8672912c9475cebb17fd7330c60 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Wed, 21 May 2025 18:43:19 -0600 Subject: [PATCH 2/3] docs: re-wording per request. --- doc/usage/referencing.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 921c2c948b3..7af7f7a5e48 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -136,8 +136,8 @@ There is also a way to directly link to documents: .. rst:role:: doc - Link to the specified document; the document name can be specified in - absolute or relative fashion. For example, if the reference + Link to the specified document; the document name is a case-sensitive + relative or absolute path. For example, if the reference ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link refers to ``sketches/parrot``. If the reference is ``:doc:`/people``` or ``:doc:`../people```, the link refers to ``people``. @@ -145,9 +145,6 @@ There is also a way to directly link to documents: If no explicit link text is given (like usual: ``:doc:`Monty Python members ```), the link caption will be the title of the given document. - Note that the string inside the single quotes must be a case-sensitive with - the file name, even on Windows. - Referencing downloadable files ------------------------------ From b29194a60c17fb789877c5967fab0430d3599b92 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Wed, 21 May 2025 18:45:06 -0600 Subject: [PATCH 3/3] docs: decided the 2nd version is more clear and complete. --- doc/usage/referencing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index 7af7f7a5e48..571d3c798bc 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -136,8 +136,8 @@ There is also a way to directly link to documents: .. rst:role:: doc - Link to the specified document; the document name is a case-sensitive - relative or absolute path. For example, if the reference + Link to the specified document; the document name can be a relative or absolute + path and is always case-sensitive, even on Windows. For example, if the reference ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link refers to ``sketches/parrot``. If the reference is ``:doc:`/people``` or ``:doc:`../people```, the link refers to ``people``.