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

Wed Aug 20 05:42:08 UTC 2025

On Tue, Aug 05, 2025 at 06:53:58PM +0200, Kamil Konieczny wrote:

Hi Kamil,

> Hi Pawel,
> On 2025-07-30 at 10:54:25 +0200, Pawel Sikora wrote:
> > From: Pawel Sikora <pawel.sikora at linux.intel.com>
> > 
> > Dear Maintainers,
> > 
> > I am submitting a series of patches to introduce a comprehensive documentation framework for the IGT GPU Tools project using MkDocs. For details regarding MkDocs please see: https://www.mkdocs.org/
> 
> Please fold all lines to 65-column, also in cover letter.

I fixed it to be <100 as checkpatch has this setting and 
config in our project - let me know if and why it really should be different.

> 
> >  
> > This effort aims to enhance organization and presentation of our documentation, making it easier for users and contributors to navigate and understand the project.
> > 
> > How to build it for review:
> > 
> > $ cd docs
> > $ pip3 install -r requirements-docs.txt
> > $ mkdocs build
> > $ mkdocs serve
> > 
> > Then, open in browser: http://127.0.0.1:8000/
> 
> Add this as a script or into a documentation itself?

Let's keep it only as a script in .gitlab-ci.yml.

> 
> > 
> > Patch 1: docs: Set up MkDocs for documentation site
> > 
> > This patch lays the foundation for the documentation site by adding essential configuration files and assets. The mkdocs.yml file is introduced to define the site's structure, including project information, navigation, theme settings(Material for MkDocs: https://squidfunk.github.io/mkdocs-material/), and plugins. 
> > 
> > Additionally, requirements-docs.txt lists the necessary dependencies for building the site with MkDocs.
> > 
> > Custom styling is applied through extra.css, which incorporates a Monokai theme, and visual assets such as the logo are included. This patch establishes the initial framework for generating the IGT GPU Tools documentation site using MkDocs. For more details on MkDocs, please refer to MkDocs Documentation.
> > 
> > Patch 2: docs: Initialize MkDocs documentation structure
> > 
> > This patch focuses on organizing the documentation content within the project.
> > 
> > The README is updated with basic content to reflect the reorganization, while detailed documentation is moved into the docs directory. 
> > 
> > The content is split across multiple markdown files, setting up a structure that allows for automatic site generation using MkDocs. 
> > This reorganization enhances the accessibility and maintenance of the documentation, providing a clear and navigable structure for users.
> 
> As you mention accessibility, could you look into
> Color Universal Design CUD here:
> https://jfly.uni-koeln.de/color/
> 
> and use guidelines from there?
> For example, it is difficult for me to read red on blue.

I did a read of this - great to know about that!
I modified theme according to some rules and made the side 
look more friendly to colorblind people. Please look at v3
and let me know what else could require adjustments.

Regards,
Pawel

> 
> Regards,
> Kamil
> 
> > 
> > Patch 3: gitlab-ci: Add MkDocs documentation support
> > 
> > This patch integrates MkDocs documentation support into the GitLab CI pipeline. 
> > It ensures that the current API reference manual (which is currently hosted on GitLab pages) is built and copied to the MkDocs documentation directory, maintaining its availability via an internal link. 
> > 
> > The MkDocs documentation from the docs directory is also built, with a relative link to api_reference/index.html included in the navigation. 
> > 
> > After both builds are complete, all content is copied into the site directory and manually moved into public for hosting on freedesktop GitLab Pages. This integration ensures that the documentation is consistently updated and accessible alongside the API reference manual.
> > 
> > Together, these patches improve the presentation and accessibility of the IGT GPU Tools project. 
> > 
> > I look forward to your feedback.
> > 
> > Regards,
> > Pawel
> > 
> > Pawel Sikora (3):
> >   docs: Set up MkDocs for documentation site
> >   docs: Initialize MkDocs documentation structure
> >   gitlab-ci: Add MkDocs documentation support
> > 
> >  .gitlab-ci.yml             |   10 +-
> >  MAINTAINERS                |    7 -
> >  README.md                  |  203 +----
> >  docs/CONTRIBUTING.md       |   82 ++
> >  docs/MAINTAINERS.md        |   16 +
> >  docs/NEWS.md               | 1471 ++++++++++++++++++++++++++++++++++++
> >  docs/api.md                |   33 +
> >  docs/assets/intel_logo.png |  Bin 0 -> 34697 bytes
> >  docs/building.md           |   28 +
> >  docs/css/extra.css         |  550 ++++++++++++++
> >  docs/faq.md                |  102 +++
> >  docs/mkdocs.yml            |  221 ++++++
> >  docs/overview.md           |  220 ++++++
> >  docs/patchwork.md          |   18 +
> >  docs/releases.md           |    0
> >  docs/requirements-docs.txt |    8 +
> >  docs/running_tests.md      |   75 ++
> >  17 files changed, 2861 insertions(+), 183 deletions(-)
> >  delete mode 100644 MAINTAINERS
> >  create mode 100644 docs/CONTRIBUTING.md
> >  create mode 100644 docs/MAINTAINERS.md
> >  create mode 100644 docs/NEWS.md
> >  create mode 100644 docs/api.md
> >  create mode 100644 docs/assets/intel_logo.png
> >  create mode 100644 docs/building.md
> >  create mode 100644 docs/css/extra.css
> >  create mode 100644 docs/faq.md
> >  create mode 100644 docs/mkdocs.yml
> >  create mode 100644 docs/overview.md
> >  create mode 100644 docs/patchwork.md
> >  create mode 100644 docs/releases.md
> >  create mode 100644 docs/requirements-docs.txt
> >  create mode 100644 docs/running_tests.md
> > 
> > -- 
> > 2.34.1
> > 