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.
