Re: [PATCH i-g-t v10 0/5] Establish MkDocs Documentation Framework for IGT GPU Tools

["Dixit, Ashutosh" <ashutosh.dixit@intel.com>]

On Thu, 09 Oct 2025 08:08:05 -0700, Kamil Konieczny wrote:
>
> Hi Jani,
> On 2025-10-08 at 11:07:00 +0300, Jani Nikula wrote:
> > On Tue, 07 Oct 2025, "Dixit, Ashutosh" <ashutosh.dixit@intel.com> wrote:
> > > On Wed, 10 Sep 2025 01:26:23 -0700, Jani Nikula wrote:
> > >>
> > >> On Tue, 09 Sep 2025, Pawel Sikora <pawel.sikora@intel.com> wrote:
> > >> > Dear Maintainers,
> > >> >
> > >> > I am submitting a series of patches to introduce a comprehensive
> > >> > documentation framework for the IGT GPU Tools project using MkDocs.
> > >>
> > >> There's been a lot of iterations in fairly quick succession, and I have
> > >> yet to see any comment from maintainers wrt my feedback [1].
> > >>
> > >> I'd rather see a clear statement "yeah let's go with MkDocs" than just
> > >> having this gradually happen without a conscious decision.
> > >
> > > I will take a slightly different approach to this. I think Jani has a valid
> > > point and if this effort were starting today, I'd say go with
> > > sphinx/rst. But as far as I see, this series has required significant
> > > effort to get to this point and is almost ready to merge.
> >
> > I don't think it had taken a significant effort by the time I first
> > brought this up, and I kind of expected to get feedback from the
> > maintainers *before* a lot more effort had been put into it.
> >
> > And now it looks like what I feared, it just gradually happened and
> > nobody stood up and made a decision.
> >
> >
> > BR,
> > Jani.
> >
>
> Imho this is not touching documentation for API, which uses gtkdoc,
> only general info spreaded in few IGT text files, so using mkdoc is
> fine by me. Also, there are converters in both ways to/from rst and
> mkdocs, if anyone in future wants to do it. This also touches only
> one link on gitlab: https://drm.pages.freedesktop.org/igt-gpu-tools
> and also make our IGT page more attractive and more accesible for
> colorblind people.
> Moving from mkdoc to sphinx also seems possible with more html/ccs
> effort needed.
>
> If anything, we could think of replacing gtkdoc with sphinx.

Yes, please, we should investigate this if possible.

> In conclusion, lets stay with mkdocs for now.

Overall, we should have given more attention to the direction we should
take when starting on this, but given where we are now, I agree we should
merge this and then ponder next steps. So this is series is:

Acked-by: Ashutosh Dixit <ashutosh.dixit@intel.com>

Thanks.
--
Ashutosh



> >
> > >
> > > I don't know how much time/effort it will take for a similar sphinx based
> > > solution (Pawel would you know?), but given where we are, it seems we
> > > should just merge this (since this would provide some missing documentation
> > > immediately). And then if we think we need a sphinx based solution and
> > > someone can be found to do that, they can switch the documentation to the
> > > sphinx based solution later.
> > >
> > > I want to elicit Pawel's feedback in particular, since he is the one doing
> > > this work.
> > >
> > > Thanks.
> > > --
> > > Ashutosh
> > >
> > >
> > >>
> > >> Cc: Everyone from MAINTAINERS.
> > >>
> > >>
> > >> BR,
> > >> Jani.
> > >>
> > >>
> > >> [1] https://lore.kernel.org/r/3d83d59669d62f004a507a25510b21f9bd273410@intel.com
> > >>
> > >>
> > >> --
> > >> Jani Nikula, Intel
> >
> > --
> > Jani Nikula, Intel