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 rcssmin
- name: Clone m.css
run: |
git clone https://github.com/mosra/m.css.git
- name: Prepare m.css stylesheets
run: |
# Navigate to m.css css directory
cd m.css/css
# Create compiled CSS manually
cat << EOF > m-documentation.compiled.css
/* Minimal CSS fallback */
body { font-family: sans-serif; line-height: 1.6; max-width: 800px; margin: 0 auto; padding: 1rem; }
h1, h2 { color: #333; }
pre { background-color: #f4f4f4; padding: 1rem; overflow-x: auto; }
EOF
cat << EOF > m-dark.compiled.css
/* Minimal dark theme CSS fallback */
body { background-color: #121212; color: #e0e0e0; }
a { color: #4CAF50; }
pre { background-color: #1e1e1e; color: #e0e0e0; }
EOF
cd ../..
- 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
# m.css and additional configurations
echo "HTML_EXTRA_STYLESHEET = $GITHUB_WORKSPACE/m.css/css/m-dark.compiled.css $GITHUB_WORKSPACE/m.css/css/m-documentation.compiled.css" >> Doxyfile
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
- name: Generate Documentation with Doxygen
run: |
doxygen Doxyfile
- name: Process Documentation with m.css (Fallback Strategy)
run: |
# Try m.css processing, but have a backup plan
set +e
python m.css/documentation/doxygen.py Doxyfile
# If m.css processing fails, create a basic index
if [ $? -ne 0 ]; then
echo "M.css processing failed. Creating fallback documentation."
# Create a basic index.html
cat << EOF > docs/html/index.html
FBGL Documentation
FBGL Documentation
Documentation generation encountered an issue. Please check the repository for the most up-to-date information.
View the project on GitHub for more details.
EOF
fi
- 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