👷 Versions are now dynamically fetched from JSON #63
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: Documentation | |
| # Only run on specific events to avoid unnecessary builds | |
| on: | |
| push: | |
| branches: | |
| - dev # Only run on dev branch pushes | |
| tags: | |
| - 'v*' # Only run on version tags | |
| pull_request: | |
| branches: | |
| - dev # Only check PRs targeting dev | |
| workflow_dispatch: # Allow manual triggering | |
| permissions: | |
| contents: write # Needed for GitHub Pages deployment | |
| jobs: | |
| docs: | |
| runs-on: ubuntu-latest | |
| # Skip job for certain types of changes | |
| if: | | |
| github.event_name == 'workflow_dispatch' || | |
| github.event_name == 'pull_request' || | |
| (github.event_name == 'push' && (github.ref == 'refs/heads/dev' || startsWith(github.ref, 'refs/tags/'))) | |
| steps: | |
| # Setup steps | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Setup Python | |
| uses: actions/setup-python@v5 | |
| - name: Install dependencies | |
| run: | | |
| pip install sphinx sphinx-book-theme myst_parser | |
| - name: Install XTL | |
| run: | | |
| pip install -e .[dev] | |
| # Version detection | |
| - name: Get package version | |
| id: get_version | |
| run: | | |
| # Function to extract clean version | |
| get_clean_version() { | |
| # Remove 'v' prefix if present | |
| echo "${1#v}" | |
| } | |
| if [[ $GITHUB_REF == refs/tags/* ]]; then | |
| # For tag pushes, use the tag name | |
| TAG_VERSION=${GITHUB_REF#refs/tags/} | |
| PACKAGE_VERSION=$(get_clean_version "$TAG_VERSION") | |
| else | |
| # For non-tag pushes, use the package version | |
| PACKAGE_VERSION=$(python -c "import xtl; print(xtl.__version__)" | tail -n 1) | |
| fi | |
| echo "PACKAGE_VERSION=$PACKAGE_VERSION" >> $GITHUB_ENV | |
| echo "version=$PACKAGE_VERSION" >> $GITHUB_OUTPUT | |
| # Generate versions information (only for deployments) | |
| - name: Generate versions.json | |
| if: | | |
| github.event_name == 'push' && | |
| (github.ref == 'refs/heads/dev' || startsWith(github.ref, 'refs/tags/')) | |
| run: | | |
| # Function to generate versions JSON from directory listing | |
| generate_versions_json() { | |
| local dirs="$1" | |
| local json="[" | |
| for dir in $dirs; do | |
| VERSION=$(basename "$dir") | |
| # Check if .versionignore file exists in this version directory | |
| if [ -f "$dir/.versionignore" ]; then | |
| echo "Skipping $VERSION (has .versionignore file)" | |
| continue | |
| fi | |
| # Extract numeric version without 'v' prefix | |
| NUM_VERSION=${VERSION#v} | |
| if [ "$json" != "[" ]; then | |
| json="$json," | |
| fi | |
| json="$json{\"version\":\"$NUM_VERSION\",\"path\":\"$VERSION/\"}" | |
| done | |
| echo "$json]" | |
| } | |
| # Clone gh-pages to get existing versions | |
| git clone --quiet --branch=gh-pages --depth=1 https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git gh-pages-clone | |
| # Find version directories | |
| VERSION_DIRS=$(find gh-pages-clone -maxdepth 1 -type d | grep -E 'v[0-9]+\.[0-9]+\.[0-9]+' | sort -r) | |
| # Generate JSON | |
| VERSIONS_JSON=$(generate_versions_json "$VERSION_DIRS") | |
| # Save versions.json for later use in the workflow | |
| echo "$VERSIONS_JSON" > versions.json | |
| # Create directories for files to be deployed to the root of gh-pages | |
| mkdir -p root_files | |
| # Copy shared files to root deployment directory | |
| cp versions.json root_files/ | |
| cp docs/source/_static/js/version-selector.js root_files/ | |
| # Clean up | |
| rm -rf gh-pages-clone | |
| # Build documentation | |
| - name: Build Sphinx documentation | |
| run: sphinx-build docs/source docs/build | |
| # Deployment steps - only run on specific events | |
| - name: Deploy to GitHub Pages (dev branch) | |
| uses: peaceiris/actions-gh-pages@v3 | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/dev' | |
| with: | |
| publish_branch: gh-pages | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: docs/build/ | |
| destination_dir: dev | |
| force_orphan: false | |
| keep_files: true | |
| - name: Deploy to GitHub Pages (version specific) | |
| uses: peaceiris/actions-gh-pages@v3 | |
| if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') | |
| with: | |
| publish_branch: gh-pages | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: docs/build/ | |
| destination_dir: v${{ env.PACKAGE_VERSION }} | |
| force_orphan: false | |
| keep_files: true | |
| - name: Deploy to GitHub Pages (latest stable) | |
| uses: peaceiris/actions-gh-pages@v3 | |
| if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') | |
| with: | |
| publish_branch: gh-pages | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: docs/build/ | |
| destination_dir: latest | |
| force_orphan: false | |
| keep_files: true | |
| # Generate root index page | |
| - name: Prepare root files | |
| if: | | |
| github.event_name == 'push' && | |
| (github.ref == 'refs/heads/dev' || startsWith(github.ref, 'refs/tags/')) | |
| run: | | |
| # Create directory for root content | |
| mkdir -p root_files | |
| # Copy root index template | |
| cp docs/source/_static/root_index.html root_files/index.html | |
| # Deploy all files to root of gh-pages | |
| - name: Deploy files to gh-pages root | |
| uses: peaceiris/actions-gh-pages@v3 | |
| if: | | |
| github.event_name == 'push' && | |
| (github.ref == 'refs/heads/dev' || startsWith(github.ref, 'refs/tags/')) | |
| with: | |
| publish_branch: gh-pages | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: root_files/ | |
| destination_dir: ./ | |
| force_orphan: false | |
| keep_files: true |