Add version switcher inside Sphinx docs sidebar #9
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: Deploy Sphinx docs to GitHub Pages | |
| on: | |
| push: | |
| branches: [master] | |
| tags: ['v*'] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.12" | |
| - name: Install dependencies | |
| run: pip install sphinx sphinx-rtd-theme | |
| - name: Build latest docs from master | |
| run: | | |
| mkdir -p _site/latest | |
| sphinx-build -b html docs _site/latest | |
| - name: Build docs for each release tag | |
| run: | | |
| for tag in $(git tag --list 'v*' --sort=-version:refname); do | |
| echo "Building docs for $tag" | |
| git checkout "$tag" -- docs/ solr/ 2>/dev/null || continue | |
| mkdir -p "_site/${tag}" | |
| sphinx-build -b html docs "_site/${tag}" 2>/dev/null || echo " Skipped $tag (build failed)" | |
| git checkout master -- docs/ solr/ 2>/dev/null | |
| done | |
| - name: Generate versions.json | |
| run: | | |
| LATEST_TAG=$(git tag --list 'v*' --sort=-version:refname | head -1) | |
| echo '[' > _site/versions.json | |
| echo " {\"version\": \"latest\", \"label\": \"latest (master)\", \"path\": \"latest\"}," >> _site/versions.json | |
| first=true | |
| for tag in $(git tag --list 'v*' --sort=-version:refname); do | |
| if [ -d "_site/${tag}" ]; then | |
| label="${tag}" | |
| if [ "$tag" = "$LATEST_TAG" ]; then | |
| label="${tag} (stable)" | |
| fi | |
| if [ "$first" = true ]; then | |
| first=false | |
| else | |
| echo "," >> _site/versions.json | |
| fi | |
| printf " {\"version\": \"%s\", \"label\": \"%s\", \"path\": \"%s\"}" "$tag" "$label" "$tag" >> _site/versions.json | |
| fi | |
| done | |
| echo "" >> _site/versions.json | |
| echo ']' >> _site/versions.json | |
| - name: Generate root redirect | |
| run: | | |
| cat > _site/index.html << 'EOF' | |
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <meta http-equiv="refresh" content="0; url=latest/"> | |
| <link rel="canonical" href="latest/"> | |
| </head> | |
| <body><a href="latest/">Redirecting to latest documentation...</a></body> | |
| </html> | |
| EOF | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: _site | |
| deploy: | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| needs: build | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |