Skip to content
Build and Deploy Documentation

Skip Oxley multi-resolution RandomData test - missing feature #65

Sign in to view logs

Skip Oxley multi-resolution RandomData test - missing feature

Skip Oxley multi-resolution RandomData test - missing feature #65

Workflow file for this run

.github/workflows/deploy-docs.yml at 354b0ed
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
with:
submodules: recursive
- 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 \
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 esys-escript (minimal for docs)
run: |
# Build only what's needed for Python API documentation
scons -j2 options_file=scons/github_ubuntu_options.py build 2>&1 | tail -100
- name: Build all documentation
run: |
# Debug: Check HDF5 installation
echo "=== Checking HDF5 libraries ==="
find /usr/lib -name "*hdf5*" -type f 2>/dev/null | head -20
ldconfig -p | grep hdf5 | head -10
# Set up Python path
export PYTHONPATH="${GITHUB_WORKSPACE}:${PYTHONPATH}"
# Set up library paths for runtime linking
# Include HDF5, SILO, and esys libraries - add both serial and standard paths
export LD_LIBRARY_PATH="${GITHUB_WORKSPACE}/lib/esys:${GITHUB_WORKSPACE}/lib:${GITHUB_WORKSPACE}/esys.trilinos/lib:/usr/lib/x86_64-linux-gnu/hdf5/serial:/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"
echo "=== Environment for docs build ==="
echo "PYTHONPATH=$PYTHONPATH"
echo "LD_LIBRARY_PATH=$LD_LIBRARY_PATH"
# Test if esys modules can be imported
echo "=== Testing esys module import ==="
python3 -c "import sys; sys.path.insert(0, '${GITHUB_WORKSPACE}'); import esys.escript; print('esys.escript imported successfully')" || echo "Failed to import esys.escript"
# Build all documentation using the 'docs' target
# This includes: basedocs (pdfdocs, examples, HTML files) + sphinxdoc
scons -j2 options_file=scons/github_ubuntu_options.py docs 2>&1 | tail -100
# Verify Sphinx documentation was built
echo "=== Verifying Sphinx API documentation ==="
if [ -d "release/doc/sphinx_api" ]; then
echo "Sphinx API directory exists"
ls -lh release/doc/sphinx_api/*.html | head -10
du -sh release/doc/sphinx_api
else
echo "ERROR: Sphinx API directory not found!"
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