Em Tue, 17 Sep 2019 09:33:11 -0700 Kees Cook <keescook@xxxxxxxxxxxx> escreveu: > On Tue, Sep 17, 2019 at 10:28:17AM -0300, Mauro Carvalho Chehab wrote: > > No matter where the profiles will physically be stored, its contents belong > > to subsystem-specific documentation, and should be visible at the same index > > file as the kAPI docs is located, as anyone interested on submitting patches > > for a subsystem should be aware about the subsystem specific policies and > > details. > > That's a good point. I think your other suggestions below address my > "find them all" case... > > > So, my vote is to store them at Documentation/*/<subsystem> (together > > with the kAPI book). > > > > > since there are > > > two ways someone would want to read profiles: > > > > > > 1) a single profile, based on a MAINTAINERS entry which includes the path > > > > That is the common case. The problem is that the MAINTAINERS file > > currently doesn't generate html output. This is not a problem for > > "old school" devs, but a newbie wanting to collaborate to a single > > specific subsystem may not notice - or understand - the importance > > of the MAINTAINERS file[1]. > > > > [1] btw, that's why I submitted a RFC, several years ago, a patch > > converting it to ReST - and later - another patch that would be parsing > > its contents and producing a ReST output. > > > > That's, by far, the most relevant usecase for the profiles, as the > > audience is the ~4k Kernel developers. > > Oh yes, having a .rst of the MAINTAINERS file would be pretty great. > Seems like it could just be a build target (and then dependency) for the > sphinx targets? You can't simply rename MAINTAINERS to .rst and let Sphinx handle it, as: - The instructions at the top will be badly parsed; - It will also parse wrong the entries. On the patches I wrote several years ago, I fixed the instructions to make them to produce something that would produce a good output. That's the easiest part. For the entries contents, the simplest solution would be something like: diff --git a/MAINTAINERS b/MAINTAINERS index 6b4bc320e6ab..ae2afb14ae01 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -147,4 +147,4 @@ F: drivers/net/ethernet/3com/3c59x.c -M: David Dillow <dave@xxxxxxxxxxxxxx> -L: netdev@xxxxxxxxxxxxxxx -S: Maintained -F: drivers/net/ethernet/3com/typhoon* +:M: David Dillow <dave@xxxxxxxxxxxxxx> +:L: netdev@xxxxxxxxxxxxxxx +:S: Maintained +:F: drivers/net/ethernet/3com/typhoon* A trivial change for a normal file, but doing this at MAINTAINERS will be really painful, as it will cause lots of conflicts. So, IMO, the best way to do it is to have a script (or to teach get_maintainers.pl) to produce a ReST output that would do the above. The latest RFC about that with I sent was this one: https://www.mail-archive.com/linux-kernel@xxxxxxxxxxxxxxx/msg1238576.html I would probably address this on a different way those days. A simple/lazy solution would be to apply the enclosed patch - or a variant of it that would place the contents of MAINTAINERS outside process/index.html, and add instructions about how to use get_maintainers.pl. Jon, Please let me know if you're willing to accept something like that. Thanks, Mauro [PATCH RFC] docs: process: add MAINTAINERS file contents Anyone working with the Kernel need to consider the contents of the MAINTAINERS file. So, add it to the ReST output. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index e2c9ffc682c5..22e5b42b8470 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -59,6 +59,9 @@ lack of a better place. volatile-considered-harmful clang-format +.. include:: ../../MAINTAINERS + :literal: + .. only:: subproject and html Indices
