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

[Jonathan Corbet <corbet@lwn.net>]

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