Skip to content

GitHub Action: Documentation Build and Deployment

This GitHub Action workflow automates the process of building and deploying project documentation using mkdocs. It ensures that documentation updates are automatically published whenever pull requests affecting specific files are merged or when triggered manually.

docs.yml

Workflow Details

Triggers (on)

  • pull_request:
    • Triggered when a pull request affecting documentation files is closed (merged) into the main branch.
    • Monitored paths:
      • Files in the docs/ directory.
      • readme.md.
  • workflow_dispatch: Allows manual triggering of the workflow via the GitHub user interface.

Job Details

build-and-publish

runs-on: ubuntu-latest

Steps:

  1. Checkout repository:

  2. Uses actions/checkout@v4 to fetch the repository contents, ensuring access to the latest documentation files.

  3. Install uv:

  4. Sets up the uv tool using astral-sh/setup-uv@v5.

  5. Set up Python:

  6. Configures Python according to the .python-version file using actions/setup-python@v5.

  7. Build documentation:

  8. Runs mkdocs build --clean via uv to generate the static documentation site. The --clean option ensures that the output directory is cleared before building.

  9. Deploy documentation:

  10. Uses peaceiris/actions-gh-pages@v3 to publish the built documentation to GitHub Pages.
  11. Inputs:
    • github_token: A Personal Access Token (PAT) stored as a repository secret.
    • publish_dir: Specifies the directory containing the built site (./site).

In summary, this workflow streamlines the process of building and deploying documentation. It automatically updates GitHub Pages whenever documentation-related files are merged into the main branch, with the added flexibility of manual triggering for on-demand updates.