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/conceptual/ — 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 in one directory so local runs, CI, and the local Docker image all share exactly one copy and nothing can drift:

The three generate-*.sh scripts are the single source of truth for each path: a developer, the CI workflows, and the Docker wrapper all invoke the same script, so a command can never drift between local and CI. 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 stays deliberately thin: its scripts/generate.sh owns no commands of its own — it just calls generate-api-diffs.sh then generate-release-notes.sh in order. All real logic lives in the engines under scripts/infra/docs/.

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 generate-*.sh scripts. 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 scripts. 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