Instruction file imported from canonical/mir (.github/instructions/docs.instructions.md). Copyright stays with the author.

Documentation

The docs live in doc/sphinx/ and use the Canonical Sphinx starter pack with MyST Markdown.

Structure

The docs follow the Diátaxis framework:

• tutorial/ — Learning-oriented first steps
• how-to/ — Task-oriented guides for compositor authors
• explanation/ — Understanding-oriented discussions
• reference/ — API reference and technical specs
• configuring/ — End-user configuration guides
• contributing/ — Developer contribution guides

Building docs

Build the docs through the CMake integration in doc/CMakeLists.txt, which wraps the Sphinx makefile and provisions its virtualenv. Configure a build directory, then invoke the doc-* targets:

cmake -B build
cmake --build build --target doc-html        # Build HTML docs
cmake --build build --target doc-linkcheck   # Validate links
cmake --build build --target doc-spelling    # Spell check
cmake --build build --target doc-serve       # Serve with live reload

doc is an alias for doc-html, and doc-checks aggregates doc-linkcheck, doc-lint-md, doc-spelling, doc-vale, and doc-woke.

API docs require Doxygen and are wired in when the build is configured with -DBUILD_DOXYGEN=ON (a doxygen target is added and doc-html then depends on it):

cmake -B build -DBUILD_DOXYGEN=ON
cmake --build build --target doc-html

SEO & metadata

• Page titles should include project context for search disambiguation (e.g., "Mir architecture" not just "Architecture").
• Open Graph: Configured via sphinxext-opengraph. The ogp_site_url and html_baseurl must include the version path to produce correct canonical/OG URLs.
• Sitemap: Generated by sphinx-sitemap. Static files (robots.txt, sitemapindex.xml) must point to the canonical base URL.
• Redirects: Managed in doc/sphinx/redirects.txt using sphinx-rerediraffe. When renaming or moving a page, always add a redirect entry.

New documentation pages

Every new doc page must include:

1. A MyST anchor before the title for cross-referencing:

   (slug-name)=
   
   # Page Title

2. A meta description in frontmatter (for search engines and social previews):

   ---
   myst:
     html_meta:
       description: Short description of this page.
   ---