name: Generate and Deploy Documentation
on:
push:
branches: [ master ]
pull_request:
branches: [ master ]
workflow_dispatch: # Allow manual triggering
permissions:
contents: read
pages: write
id-token: write
jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
submodules: recursive
- 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 doxygen graphviz ghostscript
- name: Install Python dependencies
run: |
python -m pip install --upgrade pip
pip install jinja2 Pygments
- name: Clone Doxygen Awesome
run: |
git clone https://github.com/jothepro/doxygen-awesome-css.git
- name: Generate Doxyfile
run: |
doxygen -g Doxyfile
- name: Customize Doxyfile
run: |
# Project details
sed -i 's/PROJECT_NAME = "My Project"/PROJECT_NAME = "FBGL"/' Doxyfile
sed -i 's/PROJECT_BRIEF = /PROJECT_BRIEF = "Fast and Lightweight Framebuffer Graphics Library"/' Doxyfile
# Output and input configuration
sed -i 's/OUTPUT_DIRECTORY = /OUTPUT_DIRECTORY = docs/' Doxyfile
sed -i 's/INPUT = /INPUT = fbgl.h README.md/' Doxyfile
sed -i 's/RECURSIVE = NO/RECURSIVE = YES/' Doxyfile
# Documentation generation options
sed -i 's/GENERATE_HTML = NO/GENERATE_HTML = YES/' Doxyfile
sed -i 's/HAVE_DOT = NO/HAVE_DOT = YES/' Doxyfile
sed -i 's/DOT_IMAGE_FORMAT = png/DOT_IMAGE_FORMAT = svg/' Doxyfile
# Doxygen Awesome specific configurations
echo "HTML_EXTRA_STYLESHEET = $GITHUB_WORKSPACE/doxygen-awesome-css/doxygen-awesome.css" >> Doxyfile
echo "HTML_COLORSTYLE = LIGHT" >> Doxyfile
# Additional configuration
echo "GENERATE_LATEX = NO" >> Doxyfile
echo "INTERACTIVE_SVG = YES" >> Doxyfile
echo "EXTRACT_ALL = YES" >> Doxyfile
echo "EXTRACT_PRIVATE = NO" >> Doxyfile
echo "CASE_SENSE_NAMES = NO" >> Doxyfile
echo "SEARCHENGINE = YES" >> Doxyfile
echo "USE_MDFILE_AS_MAINPAGE = README.md" >> Doxyfile
echo "MARKDOWN_SUPPORT = YES" >> Doxyfile
# Dark mode support
echo "HTML_EXTRA_STYLESHEET += $GITHUB_WORKSPACE/doxygen-awesome-css/doxygen-awesome-darkmode.css" >> Doxyfile
# Interactive tabs and fragment copy buttons
echo "HTML_EXTRA_FILES += $GITHUB_WORKSPACE/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js" >> Doxyfile
echo "HTML_EXTRA_FILES += $GITHUB_WORKSPACE/doxygen-awesome-css/doxygen-awesome-interactive-toc.js" >> Doxyfile
- name: Generate Documentation with Doxygen
run: |
doxygen Doxyfile
- name: Fallback Documentation Strategy
shell: bash
run: |
set -e
if [ -d "docs/html" ] && [ "$(ls -A docs/html)" ]; then
echo "Documentation generated successfully"
else
echo "Documentation generation failed. Creating fallback documentation."
mkdir -p docs/html
cat > docs/html/index.html << 'EOF'
FBGL Documentation
FBGL Documentation
Documentation generation failed.
Possible reasons:
- Doxygen configuration issue
- Missing source files
- Unexpected build error
Please check the repository and GitHub Actions workflow for more details.
EOF
fi
- name: List Documentation Contents
run: |
echo "Documentation directory contents:"
ls -R docs/html
- name: Setup GitHub Pages
uses: actions/configure-pages@v3
- name: Upload Documentation Artifact
uses: actions/upload-pages-artifact@v2
with:
path: './docs/html'
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: generate-docs
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2