swiftlang / swiftlang/docs

rework documentation build process - push hosting base path knowledge up front

Open
#162 0 comments 0 reactions 1 assignee View on GitHub

@heckj is already working on this.

Since Sep 8, 2026.

task
Dominant language
Python
Stars
28
Forks
5
Avg merge
18h 33m
Merged PRs (30d)
18

Description

We're doing a lot of post-processing that's a side effect of the existing docc process-archive command that applies the hosting base path (such as main, 6.4, or latest) after the various archives are merged.

Per @d-ronnqvist in the Forums (https://forums.swift.org/t/future-of-the-transform-for-static-hosting-subcommand/89304/14) - I'm mis-using that command and all of the details for hosting base paths should be known up-front when invoking the initial convert commands, and that DocC does not have a supported path for adjusting it after the fact using it's UI.

The side effect here is that content (HTML, FavIcon, etc) is getting re-rendered from the default, built-in stubs, so it's loosing content such as embedded HTML, custom values, etc - and we're working around that we post processing overrides after DocC has "done it's thing".

This means the standard library build will need to reflect the corrected hosting base path as well, and then we can work from the download and build the remaining docc archives individually with the correct values before the final step - merging them, with no trailing "transform" step.

Some post-processing is still going to be needed, but this part (at least) should get reset.

It may make sense to also have the CI build only produce a relevant collection of symbol graphs and them assemble them after the fact with the DocC converts all happening from here, in order to both simplify the logic and set this up for multi-platform builds with symbols from various platforms: Linux, Windows, macOS, iOS, etc.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.