Goals

  • Mirror the GitHub Wiki into docs/wiki/.

  • Make wiki pages part of the Sphinx site.

  • Ensure contributors in feature branches can build docs with up-to-date wiki.

  • Keep commit history clean: sync commits only happen in main.

  • Remove Docker-based wiki sync to simplify builds.

1. Add Branch-Aware GitHub Action for Wiki Sync

Create .github/workflows/sync-wiki.yml:

name: Sync Wiki to Docs

on:
  push:
    branches:
      - "**"          # Run on all branches
  pull_request:        # Ensure PR builds include wiki
  schedule:
    - cron: "0 6 * * *"  # Daily sync at 6 AM UTC
  workflow_dispatch:    # Manual trigger

jobs:
  sync-wiki:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout main repo
        uses: actions/checkout@v4
        with:
          path: main

      - name: Checkout wiki repo
        uses: actions/checkout@v4
        with:
          repository: NOAA-GSL/zyra.wiki
          path: wiki

      - name: Sync wiki into docs/wiki
        run: |
          rsync -av --delete wiki/ main/docs/wiki/

      - name: Commit wiki changes (main only)
        run: |
          cd main
          if [ "$GITHUB_REF_NAME" = "main" ]; then
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git add docs/wiki/
            if ! git diff --cached --quiet; then
              git commit -m "chore(docs): sync wiki into docs/wiki"
              git push
            else
              echo "No changes to commit"
            fi
          else
            echo "Skipping commit: branch is $GITHUB_REF_NAME"
          fi

On feature branches and PRs: wiki is synced locally so docs build works.
On main: wiki changes are committed and pushed.

2. Update Sphinx to Support Wiki Pages

In docs/source/conf.py:

extensions = [
    "myst_parser",              # Enables Markdown
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode",
]

source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
}

Install myst-parser via Poetry or pip.

3. Add Wiki to Docs Site Navigation

In docs/source/index.rst:

Welcome to Zyra's Documentation
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   api/index
   wiki/index
   contributing/wiki-sync

Create docs/wiki/index.md:

# Zyra Wiki

This section mirrors the official [GitHub Wiki](https://github.com/NOAA-GSL/zyra/wiki).

Contents are synced automatically.

4. Add Contributor Documentation

Create docs/source/contributing/wiki-sync.md:

# Wiki Sync Workflow

## Why
- Ensures wiki knowledge is AI-accessible.
- Keeps docs version-controlled with code.
- Removes duplication between Docker and CI.

## How
- GitHub Action syncs wiki → `docs/wiki/`.
- Sphinx builds wiki pages into the docs site.
- Commits only happen on `main`.

## Editing Rules
- Edit via the GitHub Wiki → synced to repo on next run.
- Do not edit `docs/wiki/` directly (overwritten on sync).

5. Remove Docker-Based Wiki Sync

  • Delete wiki fetch steps from Dockerfile.

  • Ensure docs/wiki/ is not ignored in .dockerignore.

  • Containers now build purely from repo contents.

6. Verify End-to-End

  1. Run workflow manually (workflow_dispatch).

  2. Confirm docs/wiki/ populated in branch builds.

  3. Merge to main → verify wiki commit appears.

  4. Build docs (make html) → wiki pages visible.

  5. Confirm container builds still include synced docs.

Deliverables

  1. .github/workflows/sync-wiki.yml (branch-aware).

  2. Updated conf.py with myst_parser.

  3. Updated index.rst with wiki & contributing guide.

  4. docs/wiki/index.md entrypoint.

  5. docs/source/contributing/wiki-sync.md contributor guide.

  6. Dockerfile cleaned of wiki sync logic.

Benefits

  • Always up-to-date wiki in every branch.

  • Clean commit history (sync commits only in main).

  • Docs site integrates wiki automatically.

  • Simplified container builds.

  • AI assistants can read wiki content directly from repo.