Docs #7
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Docs | |
| on: | |
| push: | |
| branches: [main] | |
| paths: | |
| - "docs/**" | |
| - "spec/**" | |
| - "mkdocs.yml" | |
| - "requirements-docs.txt" | |
| - "README.md" | |
| - "CHANGELOG.md" | |
| - "CONTRIBUTING.md" | |
| - "GOVERNANCE.md" | |
| - "ROADMAP.md" | |
| - "LIMITATIONS.md" | |
| - "CNAME" | |
| workflow_dispatch: | |
| permissions: | |
| contents: write | |
| concurrency: | |
| group: docs-deploy | |
| cancel-in-progress: false | |
| jobs: | |
| deploy: | |
| name: Build and deploy docs | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - uses: actions/setup-python@v6 | |
| with: | |
| python-version: "3.11" | |
| cache: pip | |
| - name: Install docs dependencies | |
| run: | | |
| pip install -r requirements-docs.txt | |
| pip install -e ".[dev]" | |
| - name: Configure git for gh-deploy | |
| run: | | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| - name: Assemble docs build directory | |
| run: | | |
| python3 << 'PYEOF' | |
| import os, shutil, yaml | |
| BUILD = '.docs_build' | |
| os.makedirs(BUILD, exist_ok=True) | |
| # Copy docs/ (keeps paths like docs/crosswalks/..., docs/integration/..., etc.) | |
| if os.path.exists('docs'): | |
| shutil.copytree('docs', os.path.join(BUILD, 'docs'), dirs_exist_ok=True) | |
| # Copy spec/ and examples/ (keeps paths like spec/trace-v0.1.md) | |
| for d in ['spec', 'examples', 'assets', 'crosswalks']: | |
| if os.path.exists(d): | |
| shutil.copytree(d, os.path.join(BUILD, d), dirs_exist_ok=True) | |
| # Root-level markdown files (nav references them by name) | |
| for fname in ['README.md', 'CHANGELOG.md', 'CONTRIBUTING.md', | |
| 'GOVERNANCE.md', 'ROADMAP.md', 'LIMITATIONS.md', 'CNAME']: | |
| if os.path.exists(fname): | |
| shutil.copy(fname, os.path.join(BUILD, fname)) | |
| # Generate build-specific mkdocs config | |
| with open('mkdocs.yml', encoding='utf-8') as f: | |
| config = yaml.full_load(f) | |
| config['docs_dir'] = BUILD | |
| config['site_dir'] = '/tmp/trace-spec-site' | |
| config.pop('exclude_docs', None) # build dir is already clean | |
| config.pop('custom_dir', None) # remove theme custom_dir from nested theme | |
| # Fix theme custom_dir if present | |
| if isinstance(config.get('theme'), dict): | |
| config['theme'].pop('custom_dir', None) | |
| with open('.mkdocs_build.yml', 'w', encoding='utf-8') as f: | |
| yaml.dump(config, f, allow_unicode=True, default_flow_style=False, sort_keys=False) | |
| print(f'Build directory: {BUILD}') | |
| print(f'Files: {sum(len(fs) for _, _, fs in os.walk(BUILD))}') | |
| PYEOF | |
| - name: Build and deploy to GitHub Pages | |
| run: mkdocs gh-deploy --force --clean --config-file .mkdocs_build.yml |