Add high-ROI coverage targets: direct embeddings/legacy DSL tests, he… #4215
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 | |
| on: | |
| push: | |
| branches: [ main, master ] | |
| pull_request: | |
| branches: [ main, master ] | |
| workflow_dispatch: # Allow manual triggering | |
| jobs: | |
| build-docs: | |
| name: Build Documentation | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 30 | |
| permissions: | |
| contents: write | |
| pages: write | |
| id-token: write | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v4 | |
| timeout-minutes: 2 | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: "3.10" | |
| timeout-minutes: 3 | |
| - name: Install uv | |
| run: curl -LsSf https://astral.sh/uv/install.sh | sh | |
| timeout-minutes: 5 | |
| - name: Install dependencies | |
| run: | | |
| uv venv .venv | |
| source .venv/bin/activate | |
| # Install Sphinx and extensions | |
| uv pip install sphinx sphinx-rtd-theme myst-parser m2r2 | |
| # Install package dependencies for API documentation | |
| uv pip install numpy scipy networkx matplotlib rdflib tqdm bitarray | |
| # Install py3plex package itself for autodoc to work | |
| uv pip install -e . | |
| timeout-minutes: 8 | |
| - name: Install LaTeX for PDF generation | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y texlive-latex-base texlive-latex-extra texlive-fonts-recommended texlive-latex-recommended latexmk | |
| timeout-minutes: 5 | |
| - name: Build Sphinx documentation | |
| run: | | |
| source .venv/bin/activate | |
| cd docfiles | |
| echo " Building Sphinx documentation..." | |
| # Build without treating warnings as errors to avoid breaking on autodoc issues | |
| sphinx-build -b html . _build/ --keep-going | |
| timeout-minutes: 5 | |
| - name: Build PDF documentation | |
| run: | | |
| source .venv/bin/activate | |
| cd docfiles | |
| echo " Building PDF documentation..." | |
| # Build PDF using latexpdf builder | |
| sphinx-build -b latex . _build/latex --keep-going | |
| cd _build/latex | |
| # Use latexmk with force flag to complete PDF generation despite minor errors | |
| # (e.g., Unicode characters that LaTeX can't render but doesn't prevent PDF creation) | |
| latexmk -pdf -interaction=nonstopmode -f py3plex.tex || true | |
| # Check if PDF was actually generated | |
| if [ -f "py3plex.pdf" ] && [ -s "py3plex.pdf" ]; then | |
| PDF_SIZE=$(wc -c < py3plex.pdf) | |
| echo " PDF generated successfully ($PDF_SIZE bytes)" | |
| else | |
| echo " PDF generation failed - file not created or empty" | |
| exit 1 | |
| fi | |
| timeout-minutes: 10 | |
| - name: Build Book PDF | |
| run: | | |
| source .venv/bin/activate | |
| cd book | |
| echo " Building Book PDF..." | |
| # Build LaTeX source files | |
| sphinx-build -b latex . _build/latex --keep-going | |
| cd _build/latex | |
| # Use latexmk for better dependency handling and automatic reruns | |
| latexmk -pdf -interaction=nonstopmode -f py3plex_book.tex || true | |
| # Check if PDF was generated | |
| if [ -f "py3plex_book.pdf" ] && [ -s "py3plex_book.pdf" ]; then | |
| PDF_SIZE=$(wc -c < py3plex_book.pdf) | |
| echo " Book PDF generated successfully ($PDF_SIZE bytes)" | |
| else | |
| echo " Book PDF generation failed - file not created or empty" | |
| exit 1 | |
| fi | |
| timeout-minutes: 10 | |
| - name: Copy PDFs to docs directory | |
| if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') | |
| run: | | |
| echo " Copying PDFs to docs directory..." | |
| mkdir -p docs | |
| # Verify documentation PDF exists before copying | |
| if [ ! -f "docfiles/_build/latex/py3plex.pdf" ]; then | |
| echo " Error: Documentation PDF not found at docfiles/_build/latex/py3plex.pdf" | |
| exit 1 | |
| fi | |
| cp docfiles/_build/latex/py3plex.pdf docs/py3plex_documentation.pdf | |
| ls -lh docs/py3plex_documentation.pdf | |
| # Verify book PDF exists before copying | |
| if [ ! -f "book/_build/latex/py3plex_book.pdf" ]; then | |
| echo " Error: Book PDF not found at book/_build/latex/py3plex_book.pdf" | |
| exit 1 | |
| fi | |
| cp book/_build/latex/py3plex_book.pdf docs/py3plex_book.pdf | |
| ls -lh docs/py3plex_book.pdf | |
| echo " PDFs copied successfully" | |
| timeout-minutes: 1 | |
| - name: Upload documentation artifacts | |
| uses: actions/upload-artifact@v4 | |
| if: always() | |
| with: | |
| name: documentation-html | |
| path: docfiles/_build/ | |
| retention-days: 30 | |
| timeout-minutes: 2 | |
| - name: Upload PDF artifacts | |
| uses: actions/upload-artifact@v4 | |
| if: always() | |
| with: | |
| name: documentation-pdfs | |
| path: | | |
| docfiles/_build/latex/py3plex.pdf | |
| book/_build/latex/py3plex_book.pdf | |
| retention-days: 30 | |
| timeout-minutes: 2 | |
| - name: Deploy HTML to docs folder for GitHub Pages | |
| if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') | |
| run: | | |
| echo " Deploying HTML documentation to docs/ folder..." | |
| # Remove old HTML files but keep PDF | |
| find docs -type f -name "*.html" -delete | |
| find docs -type d \( -name "_static" -o -name "_images" -o -name "_sources" \) -exec rm -rf {} + 2>/dev/null || true | |
| # Copy built HTML files to docs/ (excluding build artifacts and README) | |
| rsync -av --exclude='.buildinfo' --exclude='.doctrees' --exclude='README.md' docfiles/_build/ docs/ | |
| # Create .nojekyll to prevent Jekyll processing | |
| touch docs/.nojekyll | |
| echo " HTML files copied to docs/" | |
| ls -la docs/ | head -20 | |
| timeout-minutes: 1 | |
| - name: Commit and push documentation | |
| if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') | |
| run: | | |
| git config --local user.email "github-actions[bot]@users.noreply.github.com" | |
| git config --local user.name "github-actions[bot]" | |
| git add docs/ | |
| # Commit only if there are changes | |
| if ! git diff --staged --quiet; then | |
| git commit -m "Update documentation (HTML + PDF) [skip ci]" | |
| git push | |
| echo " Documentation committed and pushed" | |
| else | |
| echo "INFO: No changes to documentation, skipping commit" | |
| fi | |
| timeout-minutes: 2 |