SkiaSharp documentation — how the pieces fit together

This is the map of SkiaSharp's documentation system: what gets generated, by which engine, driven by which skill, on which workflow, and in which repository. Start here for the big picture, then jump to a deep dive.

Start here — what are you trying to do?

Contents

• The four kinds of documentation
• Two repositories
• The engines (scripts/infra/docs/)
• The skills
• CI automation (cross-repo)
• Local generation & Docker
• Where to go next

The four kinds of documentation

SkiaSharp ships four distinct documentation artifacts. They are produced by different tools and live in different places, which is the main reason the system can feel sprawling — this table is the whole story on one screen:

Artifacts 3 and 4 share one versioning model and one config file (versions.json); that shared model is the subject of the behavior spec. Artifact 2 is a separate concern (mdoc), but it shares the same NuGet-diff plumbing (api-diff-tools.cake) and lives next to the others.

Two repositories

flowchart LR
  subgraph A["mono/SkiaSharp (this repo)"]
    conceptual["documentation/docfx/guides/ — concept docs"]
    releases["documentation/docfx/releases/ — release notes + API diffs"]
    engines["scripts/infra/docs/ — the engines"]
    submodule["docs/ (git submodule)"]
  end
  subgraph B["mono/SkiaSharp-API-docs (the docs repo)"]
    xml["SkiaSharpAPI/ — mdoc XML reference docs"]
  end
  submodule -. "points at" .-> B
  engines --> releases
  engines -. "mdoc writes into" .-> xml

• mono/SkiaSharp (this repo) holds the conceptual docs, the release notes/api diffs tree, and all the generation engines (scripts/infra/docs/).
• mono/SkiaSharp-API-docs (the docs repo) holds the large mdoc XML reference docs and their images/examples. It is pulled into this repo as a git submodule at docs/, so the XML lives at docs/SkiaSharpAPI/. The engines in this repo run mdoc into that submodule.

Because the engines live here but the XML output lives there, the API-reference path is inherently cross-repo — see the automation section below.

The engines (scripts/infra/docs/)

All generation code lives together under scripts/infra/docs/ — the API-diff + mdoc engines (Cake) and the release-notes engine (Python) side by side. The release-notes skill keeps only the thin, stable entrypoints (prepare.sh, render.sh) that redirect to that engine, plus the AI's instructions. Nothing can drift because each path has a single canonical entry point.

Each path's entry point is its single source of truth: a developer, the CI workflows, and the Docker wrapper all invoke the same target or script, so a command can never drift between local and CI. Path 1 is the docs-api-diff Cake target, run directly by prepare.sh step 1 and by the Docker api-diffs subcommand; Path 2 runs from the release-notes skill's prepare.sh and render.sh; Path 3 runs from generate-api-docs.sh. The shared, general-purpose Cake machinery (shared.cake, download.cake) stays under scripts/infra/shared/.

The three generation paths

mdoc.exe is a .NET Framework executable. docs.cake invokes it under mono when not on Windows, so Path 3 runs on any host with mono-complete installed — a Linux CI runner or the local Docker image, not only Windows.

The skills

Three Copilot skills drive or assist these paths (.agents/skills/):

The release-notes skill exposes the whole Path 2 engine through two thin entrypoints under its own scripts/: scripts/prepare.sh is the Prepare orchestrator — it calls the docs-api-diff Cake target directly, then the engine's release-notes-data.py and release-notes-index.py; scripts/render.sh is the offline finalizer around release-notes-render.py --all. The engine those entrypoints run — release-notes-data.py, release-notes-index.py, release-notes-render.py — lives under scripts/infra/docs/ alongside the API-diff and mdoc engines; the shared, general-purpose Cake machinery (shared.cake, download.cake) stays under scripts/infra/shared/.

CI automation (cross-repo)

flowchart TB
  subgraph this["mono/SkiaSharp"]
    urn["update-release-notes\n(ubuntu-latest)"]
    sync["auto-docs-submodule-sync\n(ubuntu-latest)"]
  end
  subgraph docsrepo["mono/SkiaSharp-API-docs"]
    writer["auto-api-docs-writer\n(Linux + mono)"]
  end
  urn -->|"Prepare engines 3+4,\nthen AI Polish → one PR"| prRel["PR: release notes + api diffs\n(this repo)"]
  writer -->|"mdoc stubs +\nAI placeholder fill → PR"| prDocs["PR: XML docs\n(docs repo)"]
  prDocs -->|"merged"| sync
  sync -->|"bump docs/ submodule → PR"| prBump["PR: update submodule\n(this repo)"]

Key points:

Local generation & Docker

Everything CI does can be reproduced locally by calling the same entry points. The only host requirement beyond the .NET SDK is mono for Path 3, and gh for Path 2's PR-author lookup.

Docker is for local reproducibility only — CI does not use it. The CI runners install the same dependencies natively on Linux and call the same entry points. The image simply mirrors that dependency surface so the two stay identical.

Where to go next

• Generating or editing docs by hand → writing-docs.md
• Changing how release notes or API diffs behave → release-notes-and-api-diffs.md (change the spec first, then the code)
• The docs website (concept docs, theming, preview) → site.md