📝 Minor formatting changes to documentation #61
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 | |
| - 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") | |
| # 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") | |
| # Update template | |
| sed -i "s|__VERSIONS_JSON__|$VERSIONS_JSON|g" docs/source/_templates/layout.html | |
| # Save for root index page | |
| echo "$VERSIONS_JSON" > versions.json | |
| # Clean up | |
| rm -rf gh-pages-clone | |
| # For PRs and other non-deploy events, just use empty JSON | |
| - name: Set empty versions JSON for non-deploy builds | |
| if: | | |
| github.event_name != 'push' || | |
| (github.ref != 'refs/heads/dev' && !startsWith(github.ref, 'refs/tags/')) | |
| run: | | |
| sed -i "s|__VERSIONS_JSON__|[]|g" docs/source/_templates/layout.html | |
| # 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 and deploy root index page | |
| - name: Generate root index page | |
| if: | | |
| github.event_name == 'push' && | |
| (github.ref == 'refs/heads/dev' || startsWith(github.ref, 'refs/tags/')) | |
| run: | | |
| # Create temporary directory for root content | |
| mkdir -p temp_root | |
| # Copy root index template | |
| cp docs/source/_static/root_index.html temp_root/index.html | |
| # Use the JSON we generated earlier | |
| VERSIONS_JSON=$(cat versions.json) | |
| # Update index.html with versions JSON | |
| sed -i "s|__VERSIONS_JSON__|$VERSIONS_JSON|g" temp_root/index.html | |
| - name: Deploy root index | |
| 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: temp_root/ | |
| destination_dir: ./ | |
| force_orphan: false | |
| keep_files: true |