The answers below explain __how__, which I already know.
My question is whether this is a good or bad idea. What happens if I
change labels? Do I break people's links? Must my labels be stable
forever?
On 3/24/2023 10:45 PM, Bagas Sanjaya wrote:
On Fri, Mar 24, 2023 at 04:28:02PM -0600, Jonathan Corbet wrote:
Are links to other documents stable?
How about sections within the page?
I don't understand those questions.
You need to first add the label before desired section heading, like:
```
...
.. _foo:
Foo
===
...
```
Then elsewhere use :ref: role and specify the target label, ideally also
specifying anchor text:
```
...
This assumes that you have knowledge on :ref:`foo <foo>`.
...
```
I know I can do that.
However, what happens if someone links to my :ref:, and then I change
the label?
I found that this .rst works.
See
https://www.kernel.org/doc/html/latest/security/keys/trusted-encrypted.html
Is that OK, or is there a better way?
You wouldn't link to the rendered kernel docs normally, you'd just say
"See Documentation/security/keys/trusted-encrypted.rst".
Look at the Sphinx cheatsheets on the net for the various other ways of
making links if you need to link outside of the kernel docs.
As with internal linking, you can simply write out the link:
```
...
Check out the documentation at https://foo.bar/baz for complete
treatment on this topic.
...
```
Or if you need anchor text:
```
...
Check out `baz documentation <https://foo.bar/baz>`_ for complete
treatment on this topic`.
...
```
There is also :doc: directive if you need internal linking with anchor
text. The target can be either relative to the doc or absolute in respect
to documentation root (`Documentation/`). Do not specify filename
suffix. For example:
```
...
The general guide on :doc:`submitting patches
</process/submitting-patches>` also applies to this subsystem.
...
```
Thanks.
