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

[Pawel Sikora]

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.

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. 
2. There is already existing documentation in the project written
   in Markdown, which is widely supported by editors. 
   RST is primarily for Sphinx.

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?

> 
> 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