Skip to content

Replace gtk-doc with mkdoxy(MkDocs) for API reference

Pawel Sikora igt-dev 1 version New

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest4 patches 0 repliesNew

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/4mkdocs.yml: add mkdoxy and mdx_linkifydocs/api.md docs/requirements-docs.txt mkdocs.yml+65 -00 replies
2/4scripts: add scripts to support api reference docsscripts/list_of_tests_to_md.py scripts/update_igt_version_in_docs.py+325 -00 replies
3/4docs: add API Reference user docsdocs/api_reference.md docs/api_tests_glossary.md mkdocs.yml+120 -10 replies
4/4.gitlab-ci: add generation of API Reference with mkdocs.gitlab-ci.yml+3 -10 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.

Read the v1 thread

Cover letter [PATCH i-g-t v1 0/4] Replace gtk-doc with mkdoxy(MkDocs) for API reference

Dear maintainers,
This patch ports our API documentation by switching from gtk-doc to mkdoxy(MkDocs) with Doxygen.

Reasons to change from gtk-doc:

1. Unified toolchain: Only MkDocs needed, no external tools
2. Integrated docs: API reference now part of main docs, not external link
3. Simpler workflow: One build system for all documentation

This is a first step. Our current documentation markup has issues - missing docs, inconsistent formatting - that prevent both mkdocs and Sphinx plugins from working optimally. Once we clean up the markup across lib/tests, we can re-evaluate tools like Hawkmoth or other modern solutions. Or create a Hawkmoth integration into MkDocs via plugin.

For now, this gives us:

* Immediate improvement (unified tools, integrated docs)
* Reliable parsing (Doxygen handles existing comments)
* Foundation for future cleanup

What's included:

* mkdoxy integration within MkDocs replacing gtk-doc
* API reference page and test glossary generation
* Updated build configuration

Kind Regards,
Pawel Sikora

Pawel Sikora (4):
mkdocs.yml: add mkdoxy and mdx_linkify
scripts: add scripts to support api reference docs
docs: add API Reference user docs
.gitlab-ci: add generation of API Reference with mkdocs

 .gitlab-ci.yml                        |   4 +-
 docs/api.md                           |   2 +
 docs/api_reference.md                 | 114 ++++++++++++
 docs/api_tests_glossary.md            |   5 +
 docs/requirements-docs.txt            |   2 +
 mkdocs.yml                            |  63 ++++++-
 scripts/list_of_tests_to_md.py        | 250 ++++++++++++++++++++++++++
 scripts/update_igt_version_in_docs.py |  75 ++++++++
 8 files changed, 513 insertions(+), 2 deletions(-)
 create mode 100644 docs/api_reference.md
 create mode 100644 docs/api_tests_glossary.md
 create mode 100644 scripts/list_of_tests_to_md.py
 create mode 100644 scripts/update_igt_version_in_docs.py
Signature · 1 line
2.51.0