Shared build scripts and a reusable GitHub Actions workflow for AMWA
specification repositories, including is-*, ms-*, bcp-*, info-*, and in-*
repositories.
The workflow builds a repository's Zensical site, stores versions with Mike on
its gh-pages branch, and uploads the complete site to the AMWA documentation
server at:
/var/www/specs.amwa.tv/<site-name>
The server-facing root is a static redirect to latest/. Deployment also
writes a .htaccess file inside each individual site tree, redirecting legacy
unversioned page and asset URLs to the corresponding latest/ path without
requiring callers to add latest/ to existing links. Repositories that contain
spec.yml also publish the same metadata as spec.json at the unversioned site
root, for example https://specs.amwa.tv/in-template/spec.json. This makes
repository metadata available without a source checkout.
A versioned repository can use a very small caller workflow:
name: Documentation
run-name: ${{ case(github.event_name == 'push', '', github.event_name == 'release', format('Release - {0}', github.event.release.tag_name), format('Documentation - {0}', inputs.ref || github.ref_name)) }}
on:
push:
branches:
- 'v[0-9]+.[0-9]+-dev'
- 'v[0-9]+.[0-9]+.x'
- 'publish-*'
release:
workflow_dispatch:
inputs:
ref:
description: Optional branch or tag to rebuild
required: false
default: ''
permissions:
contents: write
concurrency:
group: amwa-documentation-${{ github.repository }}
cancel-in-progress: false
jobs:
docs:
uses: AMWA-TV/amwa-spec-docs/.github/workflows/docs.yml@main
with:
versioned: true
site-name: is-template
public-docs-root: https://specs.amwa.tv/is-template
source-ref: ${{ inputs.ref || github.ref_name }}
# Use a released tag or commit SHA once the toolkit is released.
toolkit-ref: main
secrets: inheritPush runs use GitHub's default commit title; GitHub shows the triggering
branch separately in the run metadata. Release runs are named Release - <tag>,
and manual runs are named Documentation - <ref>.
For an occasional full reconstruction of a versioned site's Mike tree, manually
dispatch the caller workflow with rebuild_all: true. This enumerates the
configured release and branch patterns and rebuilds each matching ref into
gh-pages; ordinary pushes and releases remain incremental.
For a single-version repository, use the same workflow with versioned: false:
jobs:
docs:
uses: AMWA-TV/amwa-spec-docs/.github/workflows/docs.yml@main
with:
versioned: false
site-name: in-template
public-docs-root: https://specs.amwa.tv/in-template
secrets: inheritSingle-version repositories publish only latest/ on gh-pages; they do not
create a duplicate version directory. Versioned repositories publish the
version represented by the triggering branch, release, or manually selected ref.
After every versioned deployment, latest is aliased to the highest stable
numeric GitHub release (for example v1.2.0). If there are no such releases,
latest is aliased to the highest-numbered v<major>.<minor>-dev or
v<major>.<minor>.x branch. If the selected release or branch has not yet
been published to Mike's gh-pages tree, the workflow builds that ref first;
this supports migrating repositories that already have historical releases.
Repositories can use the shared lint workflow for pull requests and standalone validation:
name: Lint
on: [push, pull_request, workflow_dispatch]
jobs:
lint:
uses: AMWA-TV/amwa-spec-docs/.github/workflows/lint.yml@mainThe documentation workflow runs the same lint workflow before building the site. It checks Markdown formatting and source data/API syntax. It intentionally does not validate Markdown links; the render workflow's Lychee step checks the completed generated site once, after Zensical has staged root-level sources and submodules.
| Input | Required | Default | Purpose |
|---|---|---|---|
site-name |
no | caller repository name | Site directory name below upload-prefix and upload name |
public-docs-root |
yes | — | Unversioned public root used for canonical URLs |
upload-prefix |
no | empty | Directory below the server document root used for upload; leave empty for a canonical site at the server root |
legacy-mapping |
no | empty | Repository-relative CSV of legacy HTML URLs; bridge pages are generated only during deployment |
versioned |
no | true |
Select versioned or fixed-latest Mike behavior |
include-submodules |
no | false |
Initialize and publish documentation from Git submodules under their source tree |
preserve-example-readme |
no | false |
Keep examples/README.md as a rendered documentation page |
source-ref |
no | triggering ref | Build a selected branch/tag, useful for manual rebuilds |
toolkit-ref |
no | main |
Shared toolkit ref; pin a release tag or SHA for production |
rebuild-all |
no | false |
Manual recovery/migration mode: rebuild all matching refs into Mike's gh-pages tree |
publish |
no | true |
Push gh-pages and upload to the AMWA server; set false for fork/PR build-only validation |
release-pattern |
no | SemVer tags | Regex used by rebuild-all to select release tags |
branch-pattern |
no | Version branches and publish-* |
Regex used by rebuild-all to select branches |
Use scripts/migrate-repositories.py to prepare several specification
repositories in one pass. It supports both versioned repositories and
non-versioned repositories that call the shared documentation workflow. The
command accepts repository names relative to a workspace or explicit repository
paths:
python scripts/migrate-repositories.py \\
--workspace /path/to/amwa-repositories \\
is-06 is-09 is-10 is-11The default is a dry run. It crawls each legacy site, derives targets from
the repository's historical Git refs for versioned repositories, or from the
current docs/ tree for non-versioned repositories, checks targets against the
current /new/ staging tree, and reports the resulting mapping counts. Apply
reviewed changes with:
python scripts/migrate-repositories.py \\
--workspace /path/to/amwa-repositories \\
--apply \\
is-06 is-09 is-10 is-11For fixed-latest repositories, use the same command with their repository
names, for example:
python scripts/migrate-repositories.py \
--workspace /path/to/amwa-repositories \
info-002 info-003 info-004 info-005 info-006Applying updates only docs.yml, README.md, and .docs/legacy-mappings.csv.
It does not commit, push, dispatch workflows, or modify/delete render.yml.
Dirty worktrees are rejected unless --allow-dirty is supplied explicitly.
The caller repository must give the reusable workflow contents: write when
publish is true, and must provide or inherit these secrets when publishing:
SSH_USERSSH_HOSTSSH_PRIVATE_KEYSSH_KNOWN_HOSTS
GITHUB_TOKEN is used by Mike to push the gh-pages branch.
The repository should contain:
README.mddocs/- optional root-level
APIs/,examples/, andmanifest/directories
A repository-level zensical.toml is optional for callers of the shared
workflow. When it is absent, prepare-docs.sh generates the common
configuration in the temporary build checkout, including repository metadata,
AMWA branding, fixed navigation where required, source-viewer assets, and the
shared 404 page. Keep a committed config only when a repository needs settings
that the shared generator cannot infer. Versioned repositories may still use
provider = "mike" under project.extra.version when maintaining their own
configuration.
For historical refs that predate the Zensical migration, the workflow fetches
metadata from the repository's current default branch. prepare-docs.sh then
generates a minimal zensical.toml in the historical build checkout and uses
the current metadata header and introductory sections (title, badges, and
repository introduction) with the historical README body. prepare-docs.sh runs from the caller repository root. It stages optional
assets, discovers RAML/JSON files, optionally generates foldable source pages when
source-viewer assets are present, rewrites source links,
and sets site_url to the effective build root. For versioned builds this
includes BUILD_REF, because Mike places the generated files below that path
without rewriting generated URLs. For non-versioned builds it remains the
unversioned public-docs-root.
The generated JSON pages use the same foldable source viewer as the YAML
source pages, with Folding/Raw views, line numbers, nested folding,
and Expand all/Collapse all controls. The generated pages do not add
separate raw-file links.
If legacy-mapping is supplied, the workflow generates static HTML bridge
pages in the runner's temporary directory and merges them into the upload. The
bridge pages are not committed to the documentation repository.
Each build also writes global-search.json at the site root. It is a compact
manifest of the built HTML pages, intended for the central NMOS index to merge
into the static global search at
https://specs.amwa.tv/nmos/global-search/.
From a checked-out documentation repository, run the shared preview helper (the repositories and this toolkit can be sibling directories):
../amwa-spec-docs/scripts/local-render.shIt copies the current working tree to a temporary directory, prepares and
builds it there, and serves the completed site. It watches the working tree and
rebuilds automatically when source files change. The working tree is not
modified. Set PORT, VENV_DIR, or RAML_DIR to customize the local tools;
set KEEP_RENDER=1 to retain the generated temporary site after stopping the
server. The preview includes spec.json at its site root.
The repository docs.yml workflow is a deployment workflow, not a fork-safe
pull-request build. It calls this reusable workflow, pushes Mike's gh-pages
branch, and uploads to the AMWA server. Those deployment steps require
repository write permission and the AMWA server secrets:
SSH_USERSSH_HOSTSSH_PRIVATE_KEYSSH_KNOWN_HOSTS
Do not copy AMWA deployment secrets into a personal fork. To check the build before opening a pull request, use the local preview helper instead. From the documentation repository, with this toolkit checked out as a sibling:
git clone https://github.com/AMWA-TV/amwa-spec-docs.git ../amwa-spec-docs
../amwa-spec-docs/scripts/local-render.shThe helper creates a temporary virtual environment, installs Zensical and
PyYAML, installs the RAML renderer with npm when required, runs
prepare-docs.sh, builds with zensical build --clean, and serves the result
locally. It requires Python 3.10 or newer, Node.js/npm when the repository has
RAML files, rsync, and network access for the initial dependency installs.
It does not modify the documentation working tree or push anything.
A fork can run the same build in GitHub Actions. The reusable workflow now
also disables publishing automatically for fork events and all pull requests,
even if the caller omits publish: false. Setting publish: false explicitly
is still recommended for a fork-only workflow as an extra safeguard. For
example, a fork-only PR workflow can contain:
name: Documentation build
on:
pull_request:
permissions:
contents: read
jobs:
docs:
uses: AMWA-TV/amwa-spec-docs/.github/workflows/docs.yml@main
with:
versioned: false
publish: false
site-name: is-template
public-docs-root: https://example.invalid/is-templateThis runs checkout, metadata preparation, branding checks, RAML rendering,
Zensical, and the link check, but skips Mike deployment, gh-pages pushes, and
the AMWA server upload. Publishing is allowed only when publish is true,
the event is not a pull request, and the repository is not marked as a fork. A
normal fork cannot faithfully test the deployment
portion because its GITHUB_TOKEN and secrets do not have access to the AMWA
publishing target.
For the local build, the caller repository should provide README.md,
docs/, and a valid zensical.toml; repositories containing RAML or JSON
sources should retain their expected APIs/, examples/, or manifest/
inputs. The build should be run from the caller repository root.
For a build without starting a server:
TOOLKIT_DIR=../amwa-spec-docs \
bash ../amwa-spec-docs/scripts/prepare-docs.sh
zensical build --cleanThe preparation step itself is normally run from the caller repository root.
The first consumers may temporarily use @main/toolkit-ref: main while this
repository is being established. Once the interface is stable, publish a
release tag (for example v1.0.0) and migrate consumers to that tag or, for
strongest reproducibility, to a commit SHA. Changes to the reusable workflow
should be treated as compatibility-sensitive because callers execute it
remotely.