Skip to content

mcts-cpu-validate docs-site GitHub Actions PRD

1. Purpose

This PRD defines the GitHub Actions workflow for building and deploying the mcts-cpu-validate documentation site.

It only covers the docs site. It does not cover training, tests, packaging, or other CI tasks. The scope needs to stay narrow so maintainers can immediately tell which workflow publishes documentation.

2. Project context

The documentation site is expected to publish at:

https://billzi2016.github.io/mcts-cpu-validate/

That gives the automation a clear job:

  • build docs-site/ when documentation-related files change
  • produce a static site
  • deploy it to GitHub Pages

It should not run on every code change, and it should not absorb unrelated pipeline work.

3. Build goals

The project needs a GitHub Actions workflow that:

  1. runs automatically after documentation-related changes on the main branch
  2. supports manual execution for recovery and debugging
  3. is limited to documentation-related paths
  4. builds the MkDocs site under docs-site/
  5. deploys the output to GitHub Pages
  6. uses clear naming for jobs, steps, and permissions

4. Why this workflow should be separate

The main repository contains a Rust and Python training system. It may eventually include:

  • Rust builds
  • Python tests
  • data validation
  • tooling checks

If docs deployment is mixed into those flows, two things get worse:

  • failures become harder to diagnose
  • documentation-only edits run unrelated work

So the docs deployment workflow should stand on its own.

5. Trigger scope

5.1 Automatic triggers

On pushes to the main branch, the workflow should only trigger when these paths change:

  • docs-site/**
  • documentation-related files under .github/workflows/**
  • root README.md
  • root README.zh.md
  • CONFIGURATION.md
  • STEP_BY_STEP_GUIDE.md
  • data/README.md

Those files either affect the published site directly or change how the docs pipeline behaves.

5.2 Manual trigger

The workflow must support workflow_dispatch. That is useful when:

  • GitHub Pages is enabled after the source change already landed
  • navigation or theme changes need a redeploy check
  • repository settings changed but the docs source did not

5.3 Concurrency

The workflow should use a concurrency group so overlapping deploys do not fight each other. Older runs should be cancellable in favor of the newest one.

6. Build inputs and outputs

6.1 Inputs

Build inputs include:

  • repository source code
  • the MkDocs configuration and pages under docs-site/
  • existing repository Markdown reused through symlinks

6.2 Outputs

The build output is a static site directory suitable for GitHub Pages, usually site/.

A maintainer should treat the output as healthy when:

  1. the build completes without navigation, linking, or missing-page failures
  2. the home page opens
  3. both language variants can be reached from the language switcher

7. Runtime requirements

7.1 Python environment

MkDocs is a Python tool, so the workflow needs a stable Python version and should install dependencies from the docs-site's own dependency definition.

7.2 Dependency source

Dependencies must come from the docs project itself. The workflow should not assume that a runner already has the right global environment.

7.3 Build command

The build command should be direct, stable, and readable. Failures should surface clearly rather than being skipped.

8. GitHub Pages deployment requirements

8.1 Deployment target

The deployment target is GitHub Pages at:

https://billzi2016.github.io/mcts-cpu-validate/

8.2 Permissions

Permissions should follow least privilege. In practice that usually means:

  • repository contents read access
  • pages write access
  • id-token write access for the official Pages deployment flow

8.3 Artifact separation

Source and build output must stay separate. The workflow should upload the built site as an artifact and deploy that artifact, rather than committing generated files back into the repository.

9. Coupling boundary with this repository

The workflow may depend on stable facts about this docs project, but it should not become a fragile script.

It may depend on:

  • docs-site/ being the docs project root
  • MkDocs being the site generator
  • bilingual pages living under docs-site/docs/zh/ and docs-site/docs/en/
  • a few root Markdown files being reused by the site

It should not depend on:

  • temporary filenames
  • personal machine paths
  • one-off conventions that only hold for the current commit

10. Maintainability requirements

The workflow file should make four things obvious:

  • when it runs
  • which environment it uses
  • where it installs dependencies from
  • how it builds and publishes the site

Step names should be specific. Vague labels make later maintenance harder.

11. Acceptance criteria

This PRD is satisfied when:

  1. the repository contains a dedicated docs deployment workflow
  2. the workflow supports workflow_dispatch
  3. automatic runs are limited to documentation-related paths
  4. the workflow installs docs dependencies and builds the MkDocs site
  5. the workflow deploys the site to GitHub Pages
  6. the workflow has concurrency control
  7. the permissions stay within least privilege

12. Explicit instructions for implementation

When implementing this PRD:

  • keep the workflow focused on the docs site
  • do not mix training or test jobs into the deployment flow
  • keep automatic triggers limited to docs-related files
  • use the standard GitHub Pages deployment path
  • treat https://billzi2016.github.io/mcts-cpu-validate/ as the published docs URL