update #178
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: Build and Deploy Documentation | |
| on: | |
| push: | |
| branches: [ main, master ] | |
| pull_request: | |
| branches: [ main, master ] | |
| jobs: | |
| docs: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Guard placeholders | |
| run: | | |
| if grep -R -n --exclude-dir=build --exclude-dir=_build --exclude-dir=.doctrees "yourusername" README.md docs; then | |
| echo "ERROR: Placeholder clone URL found" | |
| exit 1 | |
| fi | |
| if grep -R -n --exclude-dir=build --exclude-dir=_build --exclude-dir=.doctrees "Read the Docs" README.md docs; then | |
| echo "ERROR: Outdated Read the Docs reference found" | |
| exit 1 | |
| fi | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: '3.9' | |
| - name: Install system dependencies | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y pandoc | |
| - name: Install Python dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install sphinx==7.1.2 | |
| pip install sphinx-rtd-theme==1.3.0 | |
| pip install pydata-sphinx-theme==0.14.4 | |
| pip install myst-parser==2.0.0 | |
| pip install nbsphinx==0.9.1 | |
| pip install sphinx-copybutton==0.5.2 | |
| pip install sphinx-design==0.5.0 | |
| pip install sphinx-gallery==0.14.0 | |
| pip install numpy scipy matplotlib tqdm palettable Pillow | |
| # Install package in development mode with minimal dependencies | |
| pip install --no-deps -e . | |
| - name: Create required directories | |
| run: | | |
| mkdir -p docs/source/_static | |
| mkdir -p docs/source/auto_examples/images | |
| mkdir -p docs/source/auto_examples/images/thumb | |
| - name: Check source image references | |
| run: | | |
| python tools/check_docs_images.py --skip-build-check | |
| - name: Check for pre-generated figures | |
| run: | | |
| echo "Checking for figures in docs/source/auto_examples/images/" | |
| if ls docs/source/auto_examples/images/*.png 1> /dev/null 2>&1; then | |
| echo "Found pre-generated figures:" | |
| ls -la docs/source/auto_examples/images/ | grep '\.png$' | head -10 | |
| FIGURE_COUNT=$(ls docs/source/auto_examples/images/*.png | wc -l) | |
| echo "Total figures: $FIGURE_COUNT" | |
| echo "Thumbnail images are generated during Sphinx Gallery build." | |
| else | |
| echo "No pre-generated figures found" | |
| echo "Examples will show code only without figures" | |
| fi | |
| - name: List example files | |
| run: | | |
| echo "Available example files:" | |
| ls -la examples/*.py || echo "No example files found" | |
| - name: Build documentation | |
| run: | | |
| echo "Cleaning stale generated docs artifacts..." | |
| find docs/source/auto_examples -mindepth 1 -maxdepth 1 ! -name images -exec rm -rf {} + | |
| rm -rf docs/source/auto_examples/images/thumb | |
| mkdir -p docs/source/auto_examples/images/thumb | |
| rm -rf docs/build/html | |
| cd docs | |
| echo "Generating API documentation..." | |
| sphinx-apidoc -f -o source/api ../PyHydroGeophysX | |
| echo "Building HTML documentation with Sphinx Gallery..." | |
| sphinx-build -b html source build/html --keep-going -v -E | |
| echo "Build completed with exit code: $?" | |
| - name: Check built image references | |
| run: | | |
| python tools/check_docs_images.py --build-dir docs/build/html --require-build | |
| - name: Linkcheck | |
| run: | | |
| cd docs | |
| sphinx-build -b linkcheck source build/linkcheck | |
| - name: Check build results | |
| run: | | |
| echo "Checking build outputs..." | |
| if [ -f docs/build/html/index.html ]; then | |
| echo "Main documentation built successfully" | |
| else | |
| echo "ERROR: Main documentation not found" | |
| fi | |
| if [ -f docs/build/html/auto_examples/index.html ]; then | |
| echo "Examples gallery created" | |
| # Count example pages | |
| EXAMPLE_COUNT=$(find docs/build/html/auto_examples/ -name "Ex*.html" | wc -l) | |
| echo "Example pages generated: $EXAMPLE_COUNT" | |
| # Check for figures in build | |
| if ls docs/build/html/auto_examples/images/*.png 1> /dev/null 2>&1; then | |
| BUILD_FIGURE_COUNT=$(ls docs/build/html/auto_examples/images/*.png | wc -l) | |
| echo "Figures included in build: $BUILD_FIGURE_COUNT" | |
| else | |
| echo "No figures in build directory" | |
| fi | |
| else | |
| echo "Warning: Examples gallery not found" | |
| fi | |
| # List some key files for debugging | |
| echo "Key documentation files:" | |
| find docs/build/html -name "*.html" -type f | head -10 | |
| - name: Verify Sphinx Gallery output | |
| run: | | |
| echo "Sphinx Gallery specific checks..." | |
| if [ -d docs/build/html/auto_examples ]; then | |
| echo "Gallery directory structure:" | |
| find docs/build/html/auto_examples -type f -name "*.html" | head -5 | |
| if [ -d docs/build/html/auto_examples/images ]; then | |
| echo "Images directory exists in build" | |
| ls docs/build/html/auto_examples/images/ | head -5 | |
| fi | |
| fi | |
| - name: Deploy to GitHub Pages | |
| if: github.ref == 'refs/heads/main' && github.event_name == 'push' | |
| uses: peaceiris/actions-gh-pages@v3 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/build/html | |
| force_orphan: true | |
| - name: Comment deployment info | |
| if: github.ref == 'refs/heads/main' && github.event_name == 'push' | |
| run: | | |
| echo "Documentation deployed to GitHub Pages" | |
| echo "View at: https://geohang.github.io/PyHydroGeophysX/" | |
| echo "Examples: https://geohang.github.io/PyHydroGeophysX/auto_examples/" |