Re: How to cross-link to another document?

[Akira Yokosawa <akiyks@gmail.com>]

Hi Matthew,

On Wed, 6 Jul 2022 18:15:43 +0100, Matthew Wilcox wrote:
> I've tried several variants of this without success.  What's the
> correct incantation?
> 
> +++ b/Documentation/core-api/idr.rst
> @@ -17,6 +17,8 @@ solution to the problem to avoid everybody inventing their own.  The IDR
>  provides the ability to map an ID to a pointer, while the IDA provides
>  only ID allocation, and as a result is much more memory-efficient.
> 
> +The IDR interface is deprecated; please use the _`XArray` instead.

You can cross-link using .rst file's path, in this case the relative path.
(This is an extension to Sphinx for kernel documentation.)

+The IDR interface is deprecated; please use the xarray.rst instead.

If you think "the xarray.rst" looks weird in plain-text, then maybe:

+The IDR interface is deprecated; please use :doc:`the XArray <xarray>`
+instead.

Here, <xarray> points xarray.rst.  <xarray.rst> doesn't work behind
:doc:.

Or simply drop "the":

+The IDR interface is deprecated; please use xarray.rst instead.

In this case, as both idr.rst and xarray.rst are under core-api/,
the relative path would be a reasonable option.  As a bonus, it
works in both full and partial (subdirectory-wise) builds.
Cross-links using absolute paths don't work in partial builds.

> +
>  IDR usage
>  =========
> 
> +++ b/Documentation/core-api/xarray.rst
> @@ -1,4 +1,5 @@
>  .. SPDX-License-Identifier: GPL-2.0+
> +.. XArray_

In any case, a reference label at the top of a .rst file is pointless.
Please don't add a new one.

See: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#cross-referencing

Hope this helps.

        Thanks, Akira
> 
>  ======
>  XArray
> 
> I first tried "named reference, reStructuredText_;"
> and then "_`inline internal target`" and I've tried both prefixing and
> suffixing both destination and target with an underscore.  Nothing seems
> to work and sometimes I get error messages telling me it won't work,
> and sometimes I just get non-hyperlinks.
> 
> Do I have to do something like
> 
> 	:ref:`Documentation/core-api/xarray.rst <XArray>`
> ?  That would seem unnecessarily verbose.