Hi Ken, Please use Reply-to-All instead of just replying to the mailing list. This is common Linux development etiquette. On 4/3/23 08:33, Ken Goldman wrote: > 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. IMO it's hard to say without knowing how they are split up or how inter-related they are. > 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? Not necessarily. >>> 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. We don't restrict filenames from changing. If one of more change, they will just generate document build warnings or errors. Someone should see that during the kernel development process and fix it up. It happens. It's not a big deal. (This is for in-the-kernel-tree linking. For links from outside the kernel tree, that's their business...) >>> 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? We don't have such a requirement, but you can impose one on the files that you are writing if you want to. -- ~Randy
