Update user guide documentation for SolverFramework #236
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: | |
| - master | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 60 | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.11' | |
| - name: Install system dependencies | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y \ | |
| scons \ | |
| python3-markdown \ | |
| python3-sphinx \ | |
| python3-numpy \ | |
| python3-scipy \ | |
| libboost-python-dev \ | |
| libboost-numpy-dev \ | |
| libboost-random-dev \ | |
| libboost-iostreams-dev \ | |
| libnetcdf-dev libnetcdf-c++4-dev \ | |
| libsilo-dev \ | |
| libhdf5-serial-dev \ | |
| libsuitesparse-dev \ | |
| g++ \ | |
| gfortran \ | |
| git \ | |
| texlive-latex-base \ | |
| texlive-latex-extra \ | |
| texlive-fonts-recommended | |
| - name: Install Python dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install sphinx markdown numpy scipy | |
| - name: Verify LaTeX installation | |
| run: | | |
| which pdflatex | |
| pdflatex --version | |
| - name: Configure build options | |
| run: | | |
| # Detect Python version | |
| PYVER=$(python3 -c "import sys; print(f'{sys.version_info.major}{sys.version_info.minor}')") | |
| echo "Python version: $PYVER" | |
| # Detect actual boost library names | |
| echo "=== Detecting boost libraries ===" | |
| ls -la /usr/lib/x86_64-linux-gnu/libboost_python* || true | |
| ls -la /usr/lib/x86_64-linux-gnu/libboost_numpy* || true | |
| # Try to find the correct boost library suffix | |
| if [ -f "/usr/lib/x86_64-linux-gnu/libboost_python${PYVER}.so" ]; then | |
| BOOST_PY_SUFFIX="${PYVER}" | |
| elif [ -f "/usr/lib/x86_64-linux-gnu/libboost_python3.so" ]; then | |
| BOOST_PY_SUFFIX="3" | |
| else | |
| # Try to auto-detect from available files | |
| BOOST_PY_SUFFIX=$(ls /usr/lib/x86_64-linux-gnu/libboost_python*.so 2>/dev/null | head -1 | sed 's/.*libboost_python\([^.]*\)\.so/\1/') | |
| fi | |
| echo "Detected boost Python suffix: $BOOST_PY_SUFFIX" | |
| # Add boost_libs to the options file based on detected libraries | |
| echo "" >> scons/github_ubuntu_options.py | |
| echo "# Dynamic configuration based on detected boost libraries" >> scons/github_ubuntu_options.py | |
| echo "boost_libs = ['boost_python${BOOST_PY_SUFFIX}', 'boost_numpy${BOOST_PY_SUFFIX}', 'boost_random', 'boost_iostreams']" >> scons/github_ubuntu_options.py | |
| echo "" >> scons/github_ubuntu_options.py | |
| echo "# Compression support" >> scons/github_ubuntu_options.py | |
| echo "compression_libs = ['boost_iostreams', 'z', 'bz2']" >> scons/github_ubuntu_options.py | |
| echo "=== Build options file ===" | |
| cat scons/github_ubuntu_options.py | |
| - name: Build and install esys-escript | |
| run: | | |
| # Build and install esys-escript (default target includes install) | |
| scons -j2 options_file=scons/github_ubuntu_options.py 2>&1 | tee build.log | |
| # Check if build succeeded | |
| if [ ${PIPESTATUS[0]} -ne 0 ]; then | |
| echo "Build failed! Last 50 lines:" | |
| tail -50 build.log | |
| exit 1 | |
| fi | |
| echo "=== Build completed successfully ===" | |
| echo "=== Checking esys directory ===" | |
| ls -la esys/ || echo "esys/ not found" | |
| ls -la esys/escript/ || echo "esys/escript/ not found" | |
| - name: Verify esys-escript installation | |
| run: | | |
| # Set up environment | |
| export PYTHONPATH="${GITHUB_WORKSPACE}:${PYTHONPATH}" | |
| export LD_LIBRARY_PATH="${GITHUB_WORKSPACE}/lib/esys:${GITHUB_WORKSPACE}/esys.trilinos/lib:/usr/lib/x86_64-linux-gnu/hdf5/serial:/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}" | |
| echo "=== Environment ===" | |
| echo "PYTHONPATH=$PYTHONPATH" | |
| echo "LD_LIBRARY_PATH=$LD_LIBRARY_PATH" | |
| echo "=== Testing esys module import ===" | |
| python3 -c "import esys.escript; print('esys.escript imported successfully')" | |
| echo "=== Listing installed modules ===" | |
| ls -la esys/ | |
| - name: Build documentation | |
| run: | | |
| # Set up environment | |
| export PYTHONPATH="${GITHUB_WORKSPACE}:${PYTHONPATH}" | |
| export LD_LIBRARY_PATH="${GITHUB_WORKSPACE}/lib/esys:${GITHUB_WORKSPACE}/esys.trilinos/lib:/usr/lib/x86_64-linux-gnu/hdf5/serial:/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}" | |
| # Build all documentation - show full output | |
| echo "=== Building documentation ===" | |
| scons -j2 options_file=scons/github_ubuntu_options.py docs 2>&1 | tee docs.log | |
| # Check if docs build succeeded | |
| if [ ${PIPESTATUS[0]} -ne 0 ]; then | |
| echo "Documentation build failed! Last 100 lines:" | |
| tail -100 docs.log | |
| exit 1 | |
| fi | |
| # Verify Sphinx documentation was built | |
| echo "=== Verifying Sphinx API documentation ===" | |
| if [ -d "release/doc/sphinx_api" ] && [ -f "release/doc/sphinx_api/index.html" ]; then | |
| echo "Sphinx API documentation built successfully" | |
| ls -lh release/doc/sphinx_api/*.html | head -10 | |
| du -sh release/doc/sphinx_api | |
| else | |
| echo "ERROR: Sphinx API documentation not found!" | |
| echo "Contents of release/doc/:" | |
| ls -la release/doc/ || echo "release/doc/ does not exist" | |
| echo "Contents of release/doc/sphinx_api/:" | |
| ls -la release/doc/sphinx_api/ || echo "release/doc/sphinx_api/ does not exist" | |
| exit 1 | |
| fi | |
| - name: Build complete documentation | |
| run: | | |
| # Build markdown documentation | |
| mkdir -p docs | |
| # Add .nojekyll FIRST to disable Jekyll | |
| touch docs/.nojekyll | |
| # Build HTML files | |
| python3 doc/md2html.py readme README.md docs/index.html | |
| python3 doc/md2html.py installation installation.md docs/installation.html | |
| python3 doc/md2html.py options scons/templates/options.md docs/options.html | |
| # Copy full Sphinx API documentation | |
| if [ -d "release/doc/sphinx_api" ]; then | |
| cp -r release/doc/sphinx_api docs/ | |
| echo "Copied full Sphinx API documentation" | |
| # Verify genindex.html was copied | |
| if [ -f "docs/sphinx_api/genindex.html" ]; then | |
| echo "genindex.html copied successfully ($(du -h docs/sphinx_api/genindex.html | cut -f1))" | |
| else | |
| echo "WARNING: genindex.html not found in docs/sphinx_api/" | |
| fi | |
| else | |
| # Fallback: copy static assets only | |
| mkdir -p docs/sphinx_api/_static | |
| cp -r doc/sphinx_api/_static_built/* docs/sphinx_api/_static/ | |
| cat > docs/sphinx_api/index.html << 'EOF' | |
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <title>API Documentation - Build Required</title> | |
| <meta http-equiv="refresh" content="0; url=../index.html"> | |
| </head> | |
| <body> | |
| <p>Full API documentation requires building esys-escript. Redirecting to <a href="../index.html">main documentation</a>...</p> | |
| </body> | |
| </html> | |
| EOF | |
| echo "Warning: Sphinx API docs not found, using placeholder" | |
| fi | |
| # Copy example archives if available | |
| if [ -f "release/doc/escript_examples.zip" ]; then | |
| cp release/doc/escript_examples.zip docs/ | |
| echo "Copied example ZIP archive" | |
| fi | |
| if [ -f "release/doc/escript_examples.tar.gz" ]; then | |
| cp release/doc/escript_examples.tar.gz docs/ | |
| echo "Copied example TAR.GZ archive" | |
| fi | |
| # Copy user guide PDF if available | |
| mkdir -p docs/user | |
| if [ -f "release/doc/user/user.pdf" ]; then | |
| cp release/doc/user/user.pdf docs/user/ | |
| echo "Copied user guide PDF" | |
| else | |
| # Create placeholder page for user guide | |
| cat > docs/user/user.pdf.html << 'EOF' | |
| <!DOCTYPE html> | |
| <html> | |
| <head> | |
| <title>User Guide PDF - Not Available</title> | |
| <meta http-equiv="refresh" content="5; url=../index.html"> | |
| </head> | |
| <body> | |
| <h1>User Guide PDF Not Available</h1> | |
| <p>The user guide PDF requires LaTeX compilation which is not available in this automated build.</p> | |
| <p>Please refer to the <a href="../sphinx_api/index.html">Python API documentation</a> instead.</p> | |
| <p>Redirecting to <a href="../index.html">main documentation</a> in 5 seconds...</p> | |
| </body> | |
| </html> | |
| EOF | |
| echo "Warning: User guide PDF not found, created placeholder" | |
| fi | |
| # Add robots.txt | |
| echo "User-agent: *" > docs/robots.txt | |
| echo "Allow: /" >> docs/robots.txt | |
| # List what we created for debugging | |
| echo "=== Documentation structure ===" | |
| find docs -type f | head -40 | |
| echo "Documentation built successfully" | |
| - name: Configure Pages | |
| uses: actions/configure-pages@v4 | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: 'docs' | |
| 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 |