Besides the below questions, here's another:
My current module has 6 .rst files. Is that usual, or is it
recommended that the entire module be in one big file?
I know either works, but I want to follow the customary
pattern.
On 3/24/2023 6:28 PM, Jonathan Corbet wrote:
Ken Goldman <kgold@xxxxxxxxxxxxx> writes:
1. What is the recommended way to link to documents outside my tree.
Should I be doing that, or is it fragile / not recommended?
If you need to link to something elsewhere, you can certainly do so;
there are countless examples in the kernel documentation.
I know I can do it, but is it recommended or discouraged?
Are links to other documents stable?
How about sections within the page?
I don't understand those questions.
I can add a link to a .rst file. If someone links to my doc, it implies
that my filename cannot change. Similarly, if I link to another doc, I
depend on that filename not changing.
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.
That's an example. If I link like that, and then the name changes to
trusted-encryptedxxx.rst, I break.
Is that link (doc/html/latest) correct.
2. Are my pages and headings to be treated as stable, like an API? I.e.,
once I release documentation, are all the pages and headings frozen so
they will not break links?
No, there is no such requirement.
Then don't links break?
