Re: [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation)
On Sat, Sep 21, 2019 at 01:13:07PM -0600, Jonathan Corbet wrote: > Also, that file is nearly 18K lines long. If some unsuspecting person > generates a PDF and prints it, they're going to get something along the > lines of 300 pages of MAINTAINERS, which may not quite be what they had > in mind. It costs (almost) nothing to put that into HTML output, but > other formats could be painful. Is this something that can be specifically excluded from the non-HTML outputs? (Or rather, specifically included in only the HTML output?) I don't see a way to do that exactly... maybe in my RFC only the html target would get the "real" file? -- Kees Cook
Re: [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation)
Em Sat, 21 Sep 2019 13:13:07 -0600 Jonathan Corbet escreveu: > On Wed, 18 Sep 2019 08:23:26 -0300 > Mauro Carvalho Chehab wrote: > > > 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. > > [Sorry for the slowness, I'm kind of tuned out this week] > > I guess we could do that as a short-term thing. > > In truth, though, this thing is a database; printing it out linearly is > perhaps not the best thing we could do. There should be better ways we > could provide access to it. Yeah, as this is a database, instead of just outputting it on a formatted way, it is possible to generate other types of output. We could, for example, have an extension with would implement something like: .. maintainers:: Which would call get-maintainers in order to parse a subsystem-specific set of entries and printing the maintainership details. This could be added at the subsystem-specific profile, for the subsystems that have it. > > Also, that file is nearly 18K lines long. If some unsuspecting person > generates a PDF and prints it, they're going to get something along the > lines of 300 pages of MAINTAINERS, which may not quite be what they had > in mind. It costs (almost) nothing to put that into HTML output, but > other formats could be painful. Even if we go for adding a Sphinx tag that would produce a parsed output for a system-specific profile, we'll still have several other subsystems that won't have a profile for a while, so I would still consider having somewhere an output with its contents. Yeah, someone might be tempted to print it, but we could place it on a separate PDF, in order to minimize the risks of someone printing the 300+ pages. > > So I dunno, we need to think this through a bit... > > jon Thanks, Mauro
Re: [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation)
On Wed, 18 Sep 2019 08:23:26 -0300 Mauro Carvalho Chehab wrote: > 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. [Sorry for the slowness, I'm kind of tuned out this week] I guess we could do that as a short-term thing. In truth, though, this thing is a database; printing it out linearly is perhaps not the best thing we could do. There should be better ways we could provide access to it. Also, that file is nearly 18K lines long. If some unsuspecting person generates a PDF and prints it, they're going to get something along the lines of 300 pages of MAINTAINERS, which may not quite be what they had in mind. It costs (almost) nothing to put that into HTML output, but other formats could be painful. So I dunno, we need to think this through a bit... jon
Re: [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation)
Em Wed, 18 Sep 2019 10:39:32 -0700 Kees Cook escreveu: > On Wed, Sep 18, 2019 at 08:23:26AM -0300, Mauro Carvalho Chehab wrote: > > You can't simply rename MAINTAINERS to .rst and let Sphinx handle it, > > Right! Sorry, I meant what you'd suggested earlier: having a script > convert it at doc-build-time. > > > The latest RFC about that with I sent was this one: > > > > > > https://www.mail-archive.com/linux-kernel@vger.kernel.org/msg1238576.html > > Cool, I've found it on Lore now too: > https://lore.kernel.org/lkml/20160923120733.546a4...@vento.lan/ > > I think having a script generate the entire thing might be better > (instead of having duplicated instructions at the top of both files), > which I see is what Joe suggested too. Yes, I agree that having the instructions duplicated was not the best idea :-) I guess I did it, on that time, just to experiment with the approach, but my plan were to avoid the duplication on some future patch. The big issue, on that point, was the usage of the programoutput extension. Some devs didn't like using it. > > > +.. include:: ../../MAINTAINERS > > + :literal: > > Nah, let's do a full make target as you'd suggested back in that thread. > > I'll give it a shot if you don't beat me to it. :) Yeah, please give it a shot. Feel free to reuse anything from my past approaches if needed. I suspect that, if we convert the first part of MAINTAINERS to ReST syntax, we could add something similar to this to Documentation/Makefile: $(BUILDDIR)/maintainers.rst: awk '{if (match($0,"--")) exit; print}' MAINTAINERS >$(BUILDDIR)/maintainers.rst awk '/--/{y=1;next}y' MAINTAINERS|sed -E 's,^(\w:),:\1,' >>$(BUILDDIR)/maintainers.rst Thanks, Mauro
Re: [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation)
On Wed, Sep 18, 2019 at 08:23:26AM -0300, Mauro Carvalho Chehab wrote: > You can't simply rename MAINTAINERS to .rst and let Sphinx handle it, Right! Sorry, I meant what you'd suggested earlier: having a script convert it at doc-build-time. > The latest RFC about that with I sent was this one: > > > https://www.mail-archive.com/linux-kernel@vger.kernel.org/msg1238576.html Cool, I've found it on Lore now too: https://lore.kernel.org/lkml/20160923120733.546a4...@vento.lan/ I think having a script generate the entire thing might be better (instead of having duplicated instructions at the top of both files), which I see is what Joe suggested too. > +.. include:: ../../MAINTAINERS > + :literal: Nah, let's do a full make target as you'd suggested back in that thread. I'll give it a shot if you don't beat me to it. :) -- Kees Cook
Re: [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation)
Em Tue, 17 Sep 2019 09:33:11 -0700 Kees Cook 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/*/ (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 -L: net...@vger.kernel.org -S: Maintained -F: drivers/net/ethernet/3com/typhoon* +:M:David Dillow +:L:net...@vger.kernel.org +: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@vger.kernel.org/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 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