[PATCH i-g-t v3 0/3] Establish MkDocs Documentation Framework for IGT GPU Tools

[Jani Nikula]

On Fri, 22 Aug 2025, Pawel Sikora <pawel.sikora at linux.intel.com> wrote:
> On Fri, Aug 22, 2025 at 12:59:26PM +0300, Jani Nikula wrote:
>> On Wed, 20 Aug 2025, Pawel Sikora <pawel.sikora at intel.com> wrote:
>> > I am submitting a series of patches to introduce a comprehensive 
>> > documentation framework for the IGT GPU Tools project using MkDocs.
>
> Hi Jani,
>
> Thanks for your feedback - below are my observations.
>
>> 
>> I'm extremely biased, but I think there'd be more synergy in using
>> Sphinx and reStructuredText, aligning with what the kernel, mesa, and
>> several fdo projects, including our maintainer-tools and intel-docs
>> projects, are doing.
>
> I agree that there would be more synergy and unification by using
> one tool instead of two, specifically by adopting MkDocs.

There are already two tools being used, Sphinx and gtk-doc. Three if you
count scripts/igt_doc.py.

It's not about adding a second one, it's about adding a third or fourth!

> The reasons for doing it this way are:
>
> 1. This is general-purpose documentation, and Markdown is sufficient.
>    If we need more complex usage, such as an API reference, 
>    we can still generate it using Sphinx and link to it as a subpage,
>    exactly as is done with the API reference in the fourth patch.
>    I consider it an advantage and a modular design approach,
>    as even documentation serves different purposes (general purpose,
>    API, backlog, feature mapping, etc.)
>    Having a different set of tools for different types
>    of documentation modules is a matter worth considering,
>    taking into account the maturity of the solution, of course. 

On the contrary, I don't think you can really get a unified experience
with 2-4 different tools. You'll get 2-4 different web sites with
completely different styles and navigation, and you're limited in the
cross-referencing between them.

> 2. There is already existing documentation in the project written
>    in Markdown, which is widely supported by editors. 
>    RST is primarily for Sphinx.

Sphinx does support writing individual pages in Markdown if that's
desirable.

> I understand that you have a bias, as do I. 
> However, I'm not so biased that I wouldn't be willing to drop the tool
> and start using Sphinx if my use of MkDocs here is rejected.
>
> Both are great tools, so why not use both and gain knowledge about them,
> rather than limiting ourselves to just one solution? 
>
> Especially since they can complement each other and be used side by side.
>
> This is just an example of MkDocs with Markdown, but the API reference 
> will continue to use Sphinx with RST.
>
> Is having a second choice of tools and methods for creating
> automatically generated documentation, and using it for different
> purposes alongside Sphinx, a waste of resources or rather
> an opportunity for the future to have more possibilities in this area?

I should think it's desirable for any project to focus on one
documentation tool, and one documentation build, not many.

I don't know enough about MkDocs to really say if it can cover all the
needs of IGT documentation, but I do know Sphinx can. (Granted, even
that does take some plumbing to convert from gtk-doc and to incorporate
scripts/igt_doc.py as an extension. But it's possible.)

I think the question to consider is, if you were to convert all IGT
documentation to one tool, as a long term goal, does MkDocs have you
covered? I don't know the answer to that question, and maybe you do.

Ultimately, you'll have to convince the IGT maintainers and
contributors, and maybe not so much about the relative merits of the
tools, but about the burden of the fragmentation. I think it's a real
issue in many projects. People are usually streched thin, and it's just
generally easier to have one way of doing things than many.

And in all honesty, I am not the one that needs convincing. I'm not
really contributing to IGT documentation anymore, no matter which tool
it uses.


BR,
Jani.


>
>> 
>> We also have extensive experience with writing Sphinx extensions in the
>> graphics community.
>
> I would like to expand my experience in this area, as I currently have
> experience writing MkDocs extensions, and I believe that could
> be valuable as well.
>
> Kind Regards,
> Pawel
>
>> 
>> 
>> BR,
>> Jani.
>> 
>> -- 
>> Jani Nikula, Intel

-- 
Jani Nikula, Intel