mirror of
https://github.com/nextcloud/documentation.git
synced 2026-04-04 14:59:00 +07:00
273 lines
9.4 KiB
YAML
273 lines
9.4 KiB
YAML
name: "Build documentation"
|
|
|
|
on:
|
|
pull_request:
|
|
push:
|
|
branches:
|
|
- master
|
|
- stable*
|
|
|
|
permissions:
|
|
contents: read
|
|
|
|
jobs:
|
|
build:
|
|
|
|
name: Build ${{ matrix.manual.name }}
|
|
runs-on: ubuntu-latest
|
|
|
|
strategy:
|
|
matrix:
|
|
manual:
|
|
- name: "user_manual"
|
|
directory: "user_manual"
|
|
make_target: "html"
|
|
build_path: "_build/html"
|
|
build_pdf_path: "_build/latex"
|
|
publish: true
|
|
|
|
- name: "user_manual-en"
|
|
directory: "user_manual"
|
|
make_target: "html-lang-en"
|
|
build_path: "_build/html"
|
|
publish: false
|
|
|
|
- name: "developer_manual"
|
|
directory: "developer_manual"
|
|
make_target: "html"
|
|
build_path: "_build/html/com"
|
|
publish: true
|
|
|
|
- name: "admin_manual"
|
|
directory: "admin_manual"
|
|
make_target: "html"
|
|
build_path: "_build/html/com"
|
|
build_pdf_path: "_build/latex"
|
|
publish: true
|
|
|
|
steps:
|
|
- name: Cache git metadata
|
|
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
|
|
with:
|
|
path: .git
|
|
key: git-metadata-${{ github.sha }}
|
|
restore-keys: |
|
|
git-metadata-${{ github.sha }}
|
|
git-metadata
|
|
|
|
- name: Checkout repository
|
|
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
|
|
|
- name: Configure apt cache to use /dev/shm
|
|
if: ${{ matrix.manual.build_pdf_path }}
|
|
run: |
|
|
mkdir -p /dev/shm/apt/cache/archives
|
|
echo 'Dir::Cache::archives "/dev/shm/apt/cache/archives";' | sudo tee /etc/apt/apt.conf.d/apt-cache-shm
|
|
|
|
- name: Cache LaTeX apt packages
|
|
if: ${{ matrix.manual.build_pdf_path }}
|
|
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
|
|
with:
|
|
path: /dev/shm/apt/cache/archives
|
|
key: latex-apt-${{ runner.os }}-${{ hashFiles('.github/workflows/sphinxbuild.yml') }}
|
|
restore-keys: |
|
|
latex-apt-${{ runner.os }}-
|
|
|
|
- name: Install LaTeX dependencies
|
|
if: ${{ matrix.manual.build_pdf_path }}
|
|
run: |
|
|
sudo DEBIAN_FRONTEND=noninteractive apt-get update
|
|
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
|
|
--no-install-recommends \
|
|
python3-pil \
|
|
python3-pip \
|
|
texlive-fonts-recommended \
|
|
latexmk \
|
|
texlive-latex-extra \
|
|
texlive-latex-recommended \
|
|
texlive-xetex \
|
|
texlive-fonts-extra-links \
|
|
texlive-fonts-extra \
|
|
xindy
|
|
|
|
- name: Fix apt cache ownership for caching
|
|
if: ${{ matrix.manual.build_pdf_path }}
|
|
run: sudo chown -R $(id -u):$(id -g) /dev/shm/apt/cache/archives
|
|
|
|
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
|
|
with:
|
|
python-version: '3.10'
|
|
cache: 'pip'
|
|
|
|
- name: Install pip dependencies
|
|
run: pip install -r requirements.txt
|
|
|
|
- name: Build html documentation
|
|
run: cd ${{ matrix.manual.directory }} && make ${{ matrix.manual.make_target }}
|
|
|
|
- name: Compute PDF release version
|
|
if: ${{ matrix.manual.build_pdf_path }}
|
|
id: pdf_version
|
|
run: |
|
|
branch="${GITHUB_REF#refs/heads/}"
|
|
if [[ "$branch" == stable* ]]; then
|
|
echo "release=${branch#stable}" >> $GITHUB_OUTPUT
|
|
else
|
|
echo "release=latest" >> $GITHUB_OUTPUT
|
|
fi
|
|
|
|
- name: Build pdf documentation
|
|
if: ${{ matrix.manual.build_pdf_path }}
|
|
env:
|
|
DOCS_RELEASE: ${{ steps.pdf_version.outputs.release }}
|
|
run: |
|
|
set -e
|
|
cd ${{ matrix.manual.directory }}
|
|
make latexpdf
|
|
ls -la ${{ matrix.manual.build_pdf_path }}
|
|
cp ${{ matrix.manual.build_pdf_path }}/*.pdf ${{ matrix.manual.build_path }}/
|
|
|
|
- name: Upload static documentation
|
|
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
|
|
if: ${{ matrix.manual.publish }}
|
|
with:
|
|
name: ${{ matrix.manual.name }}
|
|
path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
|
|
|
|
deploy:
|
|
name: Deploy pages
|
|
needs: build
|
|
runs-on: ubuntu-latest
|
|
if: github.event_name == 'push' # Only deploy on push, not PR
|
|
|
|
permissions:
|
|
contents: write
|
|
|
|
steps:
|
|
- name: Cache git metadata
|
|
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
|
|
with:
|
|
path: .git
|
|
key: git-metadata-${{ github.sha }}
|
|
restore-keys: |
|
|
git-metadata-${{ github.sha }}
|
|
git-metadata
|
|
|
|
- name: Checkout Github Pages branch
|
|
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
|
with:
|
|
ref: gh-pages
|
|
fetch-depth: 0
|
|
token: ${{ secrets.COMMAND_BOT_PAT }}
|
|
|
|
- name: Download all ${{ needs.build.outputs.branch_name }} artifacts
|
|
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
|
|
with:
|
|
path: artifacts/
|
|
|
|
- name: Get branch name and find latest stable
|
|
id: branch
|
|
run: |
|
|
current_branch="${GITHUB_REF#refs/heads/}"
|
|
|
|
# Find the highest numbered stable branch from the remote
|
|
highest_stable=$(git ls-remote --heads origin | sed -n 's?.*refs/heads/stable\([0-9]\{2\}\)$?\1?p' | sort -n | tail -1)
|
|
highest_stable_branch="stable${highest_stable}"
|
|
|
|
echo "Current branch: $current_branch"
|
|
echo "Highest stable branch found: $highest_stable_branch"
|
|
|
|
# Map actual branch names to deployment folder names
|
|
case "$current_branch" in
|
|
"master")
|
|
echo "branch_name=latest" >> $GITHUB_OUTPUT
|
|
;;
|
|
"$highest_stable_branch")
|
|
echo "branch_name=stable" >> $GITHUB_OUTPUT
|
|
# Also record the numeric version so we can publish to server/<number>/ too
|
|
echo "version_name=${highest_stable}" >> $GITHUB_OUTPUT
|
|
;;
|
|
*)
|
|
# Remove stable prefix for current branch
|
|
current_branch="${current_branch#stable}"
|
|
echo "branch_name=$current_branch" >> $GITHUB_OUTPUT
|
|
;;
|
|
esac
|
|
|
|
echo "Deployment folder name: ${{ steps.branch.outputs.branch_name }}"
|
|
echo "Version name for additional deployment (if applicable): ${{ steps.branch.outputs.version_name }}"
|
|
|
|
- name: Merge ${{ steps.branch.outputs.branch_name }} documentation artifacts into gh-pages
|
|
run: |
|
|
# List artifacts
|
|
ls -la artifacts/*/
|
|
|
|
# Cleanup old documentation
|
|
rm -rf ${{ steps.branch.outputs.branch_name }}
|
|
rm -rf server/${{ steps.branch.outputs.branch_name }}
|
|
mkdir -p server/${{ steps.branch.outputs.branch_name }}
|
|
|
|
# Copy all built documentation into dedicated subdirectories
|
|
for artifact in artifacts/*; do
|
|
if [ -d "$artifact" ]; then
|
|
manual_name="$(basename "$artifact")"
|
|
mkdir -p "server/${{ steps.branch.outputs.branch_name }}/$manual_name"
|
|
cp -r "$artifact/"* "server/${{ steps.branch.outputs.branch_name }}/$manual_name/"
|
|
fi
|
|
done
|
|
|
|
# Move pdf files to the root of the branch_name
|
|
mv server/${{ steps.branch.outputs.branch_name }}/*/*.pdf server/${{ steps.branch.outputs.branch_name }}/ || true
|
|
|
|
# If this is the highest stable branch, also deploy to its versioned folder
|
|
if [ -n "${{ steps.branch.outputs.version_name }}" ]; then
|
|
rm -rf server/${{ steps.branch.outputs.version_name }}
|
|
cp -r server/${{ steps.branch.outputs.branch_name }} server/${{ steps.branch.outputs.version_name }}
|
|
fi
|
|
|
|
# Cleanup
|
|
find . -type d -empty -delete
|
|
rm -rf artifacts
|
|
|
|
- name: Add various redirects for go.php and user_manual english version
|
|
run: |
|
|
# Fetch source branches so git checkout origin/... works from the gh-pages checkout
|
|
git fetch origin ${{ github.event.repository.default_branch }} ${{ github.ref_name }}
|
|
|
|
# Generate go.php redirect from main branch
|
|
git checkout origin/${{ github.event.repository.default_branch }} -- go.php/index.html
|
|
mkdir -p server/${{ steps.branch.outputs.branch_name }}/go.php
|
|
mv go.php/index.html server/${{ steps.branch.outputs.branch_name }}/go.php/index.html
|
|
|
|
# Generate user_manual english redirect
|
|
git checkout origin/${{ github.ref_name }} -- user_manual/index.html
|
|
mkdir -p server/${{ steps.branch.outputs.branch_name }}/user_manual
|
|
mv user_manual/index.html server/${{ steps.branch.outputs.branch_name }}/user_manual/index.html
|
|
|
|
- name: Commit ${{ steps.branch.outputs.branch_name }} documentation and push to gh-pages
|
|
run: |
|
|
git config --local user.email "nextcloud-command@users.noreply.github.com"
|
|
git config --local user.name "nextcloud-command"
|
|
git add .
|
|
git diff --staged --quiet || git commit -m "chore: deploy documentation for ${{ steps.branch.outputs.branch_name }}"
|
|
# Ensure we are up to date with the remote gh-pages branch
|
|
git pull --rebase origin gh-pages || true
|
|
git push origin gh-pages || echo "Nothing to push (expected if no changes)"
|
|
env:
|
|
GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }}
|
|
|
|
summary:
|
|
needs: build
|
|
runs-on: ubuntu-latest
|
|
if: always()
|
|
|
|
permissions:
|
|
contents: read
|
|
|
|
name: build-deploy-summary
|
|
|
|
steps:
|
|
# Only check if the build was successful
|
|
- name: Summary status
|
|
run: if ${{ needs.build.result != 'success' }}; then exit 1; fi
|