[PATCH 0/2] docs: Add support for relative paths in automarkup

[PATCH 0/2] docs: Add support for relative paths in automarkup

[Nícolas F. R. A. Prado]

As Jon previously noted [1], it would be nice if automarkup supported relative
paths as well when cross-referencing to other documents. This adds the support
for it, and documents it.

Jon, after applying this, 43bc3ed73639 ("docs: dt: Use full path to enable
cross-reference") could be reverted without the link stopping to work.

[1] https://lore.kernel.org/linux-doc/20201130142404.6ef6689e@lwn.net/

Nícolas F. R. A. Prado (2):
  docs: Enable usage of relative paths to docs on automarkup
  docs: Document cross-referencing using relative path

 Documentation/doc-guide/sphinx.rst | 30 ++++++++++++++++++++----------
 Documentation/sphinx/automarkup.py |  7 +++++--
 2 files changed, 25 insertions(+), 12 deletions(-)

-- 
2.30.0

[PATCH 1/2] docs: Enable usage of relative paths to docs on automarkup

[Nícolas F. R. A. Prado]

Previously, a cross-reference to another document could only be created
by writing the full path to the document starting from the
Documentation/ directory.

Extend this to also allow relative paths to be used. A relative path
would be just the path, like ../filename.rst, while the absolute path
still needs to start from Documentation, like Documentation/filename.rst.

As part of this change, the .rst extension is now required for both
types of paths, since not requiring it would cause the regex to be too
generic.

Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
---
 Documentation/sphinx/automarkup.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 953b24b6e2b4..4b6aef9b35db 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -51,7 +51,7 @@ RE_typedef = re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)', flags=ascii_p3)
 # Detects a reference to a documentation page of the form Documentation/... with
 # an optional extension
 #
-RE_doc = re.compile(r'\bDocumentation(/[\w\-_/]+)(\.\w+)*')
+RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.rst')
 
 RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
 
@@ -234,7 +234,10 @@ def markup_doc_ref(docname, app, match):
     #
     # Go through the dance of getting an xref out of the std domain
     #
-    target = match.group(1)
+    absolute = match.group(1)
+    target = match.group(2)
+    if absolute:
+       target = "/" + target
     xref = None
     pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc',
                                   reftarget = target, modname = None,
-- 
2.30.0

[PATCH 2/2] docs: Document cross-referencing using relative path

[Nícolas F. R. A. Prado]

Update the Cross-referencing section to explain how to create a
cross-reference to a document using relative paths and with no
additional syntax, by relying on automarkup.py.

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
---
 Documentation/doc-guide/sphinx.rst | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 36ac2166ad67..ec3e71f56009 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -340,16 +340,26 @@ Rendered as:
 Cross-referencing
 -----------------
 
-Cross-referencing from one documentation page to another can be done by passing
-the path to the file starting from the Documentation folder.
-For example, to cross-reference to this page (the .rst extension is optional)::
-
-    See Documentation/doc-guide/sphinx.rst.
-
-If you want to use a relative path, you need to use Sphinx's ``doc`` directive.
-For example, referencing this page from the same directory would be done as::
-
-    See :doc:`sphinx`.
+Cross-referencing from one documentation page to another can be done simply by
+writing the path to the document file, no special syntax required. The path can
+be either absolute or relative. For absolute paths, start it with
+"Documentation/". For example, to cross-reference to this page, all the
+following are valid options, depending on the current document's directory (note
+that the ``.rst`` extension is required)::
+
+    See Documentation/doc-guide/sphinx.rst. This always works.
+    Take a look at sphinx.rst, which is at this same directory.
+    Read ../sphinx.rst, which is one directory above.
+
+If you want the link to have a different rendered text other than the document's
+title, you need to use Sphinx's ``doc`` role. For example::
+
+    See :doc:`my custom link text for document sphinx <sphinx>`.
+
+For most use cases, the former is preferred, as it is cleaner and more suited
+for people reading the source files. If you come across a ``:doc:`` usage that
+isn't adding any value, please feel free to convert it to just the document
+path.
 
 For information on cross-referencing to kernel-doc functions or types, see
 Documentation/doc-guide/kernel-doc.rst.
-- 
2.30.0

Re: [PATCH 0/2] docs: Add support for relative paths in automarkup

[Jonathan Corbet]

Nícolas F. R. A. Prado <nfraprado@protonmail.com> writes:

> As Jon previously noted [1], it would be nice if automarkup supported relative
> paths as well when cross-referencing to other documents. This adds the support
> for it, and documents it.
>
> Jon, after applying this, 43bc3ed73639 ("docs: dt: Use full path to enable
> cross-reference") could be reverted without the link stopping to work.
>
> [1] https://lore.kernel.org/linux-doc/20201130142404.6ef6689e@lwn.net/
>
> Nícolas F. R. A. Prado (2):
>   docs: Enable usage of relative paths to docs on automarkup
>   docs: Document cross-referencing using relative path
>
>  Documentation/doc-guide/sphinx.rst | 30 ++++++++++++++++++++----------
>  Documentation/sphinx/automarkup.py |  7 +++++--
>  2 files changed, 25 insertions(+), 12 deletions(-)

So I finally got around to playing with this set.  One thing I found is
that some of the references that were being caught before were not
now...  after far too much time, I figured out that the problem was
references to .txt files, of which we have quite a few in the docs.
admin-guide/kernel-parameters.txt in particular is quite popular.
Before this change, those were being turned into xrefs, afterward not.

To address that, I applied this little tweak:

-RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.rst')
+RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)')

That seems to make things work properly again.

While tracking this down I put in a print for failing cross references,
and noted that we have quite a few; it's a useful way to see where the
stale references are.  Maybe I'll try to hack together something to make
those stand out so we can fix them.

Thanks,

jon

Re: [PATCH 0/2] docs: Add support for relative paths in automarkup

[Randy Dunlap]

On 2/4/21 3:28 PM, Jonathan Corbet wrote:
> Nícolas F. R. A. Prado <nfraprado@protonmail.com> writes:
> 
>> As Jon previously noted [1], it would be nice if automarkup supported relative
>> paths as well when cross-referencing to other documents. This adds the support
>> for it, and documents it.
>>
>> Jon, after applying this, 43bc3ed73639 ("docs: dt: Use full path to enable
>> cross-reference") could be reverted without the link stopping to work.
>>
>> [1] https://lore.kernel.org/linux-doc/20201130142404.6ef6689e@lwn.net/
>>
>> Nícolas F. R. A. Prado (2):
>>   docs: Enable usage of relative paths to docs on automarkup
>>   docs: Document cross-referencing using relative path
>>
>>  Documentation/doc-guide/sphinx.rst | 30 ++++++++++++++++++++----------
>>  Documentation/sphinx/automarkup.py |  7 +++++--
>>  2 files changed, 25 insertions(+), 12 deletions(-)
> 
> So I finally got around to playing with this set.  One thing I found is
> that some of the references that were being caught before were not
> now...  after far too much time, I figured out that the problem was
> references to .txt files, of which we have quite a few in the docs.
> admin-guide/kernel-parameters.txt in particular is quite popular.
> Before this change, those were being turned into xrefs, afterward not.
> 
> To address that, I applied this little tweak:
> 
> -RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.rst')
> +RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)')
> 
> That seems to make things work properly again.
> 
> While tracking this down I put in a print for failing cross references,
> and noted that we have quite a few; it's a useful way to see where the
> stale references are.  Maybe I'll try to hack together something to make
> those stand out so we can fix them.
> 
> Thanks,
> 
> jon

Hi,
I just sent a patch for file name changes in
Documentation/input/ff.rst
(https://lore.kernel.org/linux-input/20210203050842.24190-1-rdunlap@infradead.org/T/#u).

I sent it to the INPUT maintainer because I thought that he would
want to review the changes.

I could resend it to the DOCS maintainer.  :)

-- 
~Randy

Re: [PATCH 0/2] docs: Add support for relative paths in automarkup

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> I just sent a patch for file name changes in
> Documentation/input/ff.rst
> (https://lore.kernel.org/linux-input/20210203050842.24190-1-rdunlap@infradead.org/T/#u).
>
> I sent it to the INPUT maintainer because I thought that he would
> want to review the changes.
>
> I could resend it to the DOCS maintainer.  :)

Things are probably fine as they are, but feel free to send it my way if
you don't get a response over there.

Thanks,

jon

Re: [PATCH 0/2] docs: Add support for relative paths in automarkup

[Nícolas F. R. A. Prado]

Em Thu Feb 4, 2021 at 8:28 PM -03, Jonathan Corbet escreveu:
>
> Nícolas F. R. A. Prado <nfraprado@protonmail.com> writes:
>
> > As Jon previously noted [1], it would be nice if automarkup supported relative
> > paths as well when cross-referencing to other documents. This adds the support
> > for it, and documents it.
> >
> > Jon, after applying this, 43bc3ed73639 ("docs: dt: Use full path to enable
> > cross-reference") could be reverted without the link stopping to work.
> >
> > [1] https://lore.kernel.org/linux-doc/20201130142404.6ef6689e@lwn.net/
> >
> > Nícolas F. R. A. Prado (2):
> >   docs: Enable usage of relative paths to docs on automarkup
> >   docs: Document cross-referencing using relative path
> >
> >  Documentation/doc-guide/sphinx.rst | 30 ++++++++++++++++++++----------
> >  Documentation/sphinx/automarkup.py |  7 +++++--
> >  2 files changed, 25 insertions(+), 12 deletions(-)
>
> So I finally got around to playing with this set. One thing I found is
> that some of the references that were being caught before were not
> now... after far too much time, I figured out that the problem was
> references to .txt files, of which we have quite a few in the docs.
> admin-guide/kernel-parameters.txt in particular is quite popular.
> Before this change, those were being turned into xrefs, afterward not.

Hm, but what is actually being linked to is the .rst of same name,
admin-guide/kernel-parameters.rst. Both when adding a file to the Sphinx's
index, as well as when cross-referencing, the file name is used without the
extension, because the .rst extension is implied.

In the case of admin-guide/kernel-parameters.txt though, the .rst file includes
the .txt file, so it actually makes sense to cross-reference to the .rst when
writing the path to the .txt. But in the case of
core-api/refcount-vs-atomic.rst, for example, where there is a reference to
memory-barriers.txt, which is a file with no .rst counterpart, it will
fail to cross-reference. At the moment that's harmless, but it will become a
problem after we enable warnings.

>
> To address that, I applied this little tweak:
>
> -RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.rst')
> +RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)')
>
> That seems to make things work properly again.
>
> While tracking this down I put in a print for failing cross references,
> and noted that we have quite a few; it's a useful way to see where the
> stale references are. Maybe I'll try to hack together something to make
> those stand out so we can fix them.

That was already on my backlog, so I could probably do it in the next few days
:) (if you don't get to it first, of course).

Thanks,
Nícolas