Re: [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation)

Mauro Carvalho Chehab
2019-09-18T18:35:27Z

Em Wed, 18 Sep 2019 10:39:32 -0700
Kees Cook <keescook@chromium.org> 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.546a4b7a@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