Integrating library-documentation-action-v2 Functionality into pony-doc

[SeanTAllen]

Background

The library-documentation-action-v2 GitHub Action generates documentation for Pony libraries and deploys it to GitHub Pages. It wraps ponyc --docs (soon pony-doc) with post-processing that filters documentation output to only the library's own packages, resolves cross-references to external documentation, and runs mkdocs build.

With pony-doc now replacing docgen.c as the documentation generator, the filtering and link resolution functionality should move into pony-doc itself. This document specifies what needs to be integrated and how.

What library-documentation-action-v2 Does Today

The action takes three inputs: library_name, docs_build_dir (where generated docs are placed), and site_url (canonical site URL for mkdocs). Its entrypoint.py performs these steps in order:

1. Runs make docs to generate full documentation (all packages including dependencies)
2. Removes doc files for packages outside the library (keeps files starting with {library_name}-)
3. Removes source directories for packages outside the library
4. Trims mkdocs.yml nav entries to only library packages and sets site_url
5. Trims index.md package listing to only library packages
6. Reads _corral/{dep}/corral.json files to build a package-to-documentation-URL map
7. Rewrites dead links in remaining doc files to point to external documentation URLs
8. Runs mkdocs build to produce the final HTML site

The action filters at the file level — it generates everything, then deletes what doesn't belong. It determines which package a doc file belongs to by parsing the TQFN filename (splitting on -, dropping the last segment to get the package name, rejoining with /). This string-splitting heuristic works because Pony type names can't contain dashes, but it's fragile in principle.

What Moves Into pony-doc

General (backend-agnostic) — lives in the extractor

Package filtering by library name. When a library name is provided, only packages belonging to that library are included in the DocProgram IR. A package belongs to the library if its qualified name equals {library_name} or starts with {library_name}/. Dependencies are still compiled (types reference them), but they're excluded from the documentation output.

Since filtering happens during extraction, the action's post-processing steps (removing files, trimming nav, trimming index) become unnecessary — the backend never sees the filtered packages and never generates output for them. pony-doc has direct access to each type's package through the AST, so it doesn't need the action's filename-parsing heuristic.

External documentation URL map. pony-doc reads corral.json files from the corral workspace (_corral/) to build a mapping from package name to documentation URL. Each corral.json contains an info.documentation_url field and a packages array listing the package names that dependency provides. All packages listed in a dependency's corral.json map to that dependency's documentation_url.

The stdlib is not a corral dependency (it's built into ponyc), so it won't appear in any corral.json. Packages not found in any dependency's corral.json default to https://stdlib.ponylang.io/. This is a best-effort heuristic — it's correct for stdlib packages (the common case), but non-stdlib dependencies that lack a corral.json entirely will get incorrect links pointing to stdlib.

Note: the action has a bug here. When a dependency's corral.json lists packages but omits documentation_url (or has it as empty string), the action maps those packages to "", producing broken relative links instead of falling back to stdlib. pony-doc fixes this by treating absent or empty documentation_url the same as "not found" — the stdlib fallback applies.

Marking external references. When --library-name is active and a DocNominal type's definition resolves to a package that was filtered out, the nominal is marked as "external" with the appropriate base URL from the documentation URL map. Without --library-name, no packages are filtered out and this logic does not apply.

The IR change: DocNominal gets a new external_url: (String | None) field. When None, the type is local and links to a local file. When set, the backend uses it as the base URL for the link.

Backend-specific — lives in each backend implementation

Rendering external links. When a DocNominal has an external_url, the backend renders its link using the external base URL instead of a local file reference. For the mkdocs backend, this means generating [Name](https://external.url/tqfn/) instead of [Name](tqfn.md). External link resolution only applies to type references within entity documentation pages, not to package-level links (which are eliminated by filtering).

What Does NOT Move Into pony-doc

site_url injection. This is a pure mkdocs configuration concern. It tells mkdocs the canonical site URL for generating correct absolute URLs in HTML output (sitemaps, canonical links, 404 page asset paths). It has no effect on the markdown pony-doc generates. Users set this when they run mkdocs build, not when they run pony-doc.

docs_build_dir. This is a build orchestration concern — it tells the action where to find the generated docs. pony-doc already has --output for this purpose.

Running mkdocs build. pony-doc generates markdown and configuration; building the final HTML site remains the caller's responsibility.

CLI Interface

Two new options:

• --library-name NAME — filter packages to only those belonging to the named library. Implies reading corral.json files for external link resolution.
• --corral-dir DIR — path to the corral workspace directory (default: _corral relative to the package being documented). Only meaningful when --library-name is set.

corral.json Format

For reference, the relevant fields in a corral.json file:

{
  "info": {
    "documentation_url": "https://example.github.io/my-library/"
  },
  "packages": [
    "my-library",
    "my-library/subpackage"
  ]
}

• documentation_url may be absent or empty string — pony-doc treats both as "not found" and applies the stdlib fallback URL (fixing a bug in the action where these cases produce broken relative links)
• packages may be absent — dependencies without it contribute nothing to the URL map
• documentation_url may or may not have a trailing slash — pony-doc normalizes it

How External Link Resolution Works

1. During extraction, build the documentation URL map from corral.json files
2. When extracting types, if a DocNominal's definition resolves to a package not in the filtered set, set its external_url field to the appropriate base URL from the documentation URL map
3. During rendering, the backend checks each nominal: if it has an external_url, render the link as {external_url}{tqfn}/ instead of {tqfn}.md

The TQFN-to-URL conversion follows the same pattern the action uses: the TQFN string becomes the URL path segment with a trailing / (e.g., TQFN semver-Version becomes URL path semver-Version/).

[SeanTAllen]

Decision: CLI option for corral project directory

The --corral-dir option described in the document is revised. Instead of pointing at the _corral/ directory directly, the option takes the path to the corral project directory — the directory containing both corral.json and _corral/.

Revised CLI option

• --corral-dir DIR — path to the corral project directory (must contain corral.json and _corral/). Only meaningful when --library-name is set.

Validation

pony-doc checks for both files at the given path:

1. If corral.json doesn't exist at DIR/corral.json: error with "Couldn't locate corral.json in {DIR}"
2. If corral.json exists but DIR/_corral/ doesn't exist: error with "Couldn't locate _corral in {DIR} — did you forget to run corral fetch?"

No implicit searching (walking up directories to find corral.json). The user provides the explicit path.

Reading dependency metadata

Same as the action: scan DIR/_corral/*/corral.json for each dependency's packages array and documentation_url. This is a pragmatic choice — it works today and can be improved later (e.g., corral could expose this data through a command).