Skip to content
Documentation

Documentation #19

Sign in to view logs

Documentation

Documentation #19

Workflow file for this run

.github/workflows/docs.yml at 3f7b57f
name: Documentation
on:
push:
paths:
- '.github/workflows/docs.yml'
- 'lua/**'
- 'docs/**'
- 'tools/docs/**'
branches:
- development
- master
pull_request:
paths:
- '.github/workflows/docs.yml'
- 'lua/**'
- 'docs/**'
- 'tools/docs/**'
permissions:
contents: read
# The deploy pushes to gh-pages, so a second run starting mid-deploy would race
# the first for the branch. Queue them instead, and let a superseded build drop:
# the site is a full rebuild every time, so only the newest one matters.
concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
name: Build
runs-on: ubuntu-latest
permissions:
contents: write
env:
LUALS_VERSION: 3.18.2
SITE_URL: https://photonle.github.io/Photon
steps:
-
name: Checkout
uses: actions/checkout@v7
# Only this one. `submodules: true` would pull anything else added later,
# none of which the docs build reads.
-
name: Fetch base-game type definitions
run: git submodule update --init tools/docs/vendor/glua-api-snippets
-
name: Setup Python
uses: actions/setup-python@v7
with:
python-version: '3.11'
-
name: Install Python Dependencies
run: pip install -r tools/docs/requirements.txt
-
name: Run generator tests
run: python3 -m unittest test_generate
working-directory: tools/docs
-
name: Install LuaLS
run: |
wget -q https://github.com/LuaLS/lua-language-server/releases/download/$LUALS_VERSION/lua-language-server-$LUALS_VERSION-linux-x64.tar.gz
mkdir -p /tmp/luals
tar -xzf lua-language-server-$LUALS_VERSION-linux-x64.tar.gz -C /tmp/luals
-
name: Generate LuaLS JSON
run: |
# LuaLS writes nothing at all if --doc_out_path does not already
# exist, and still prints "Documentation exported:" and exits 0 - so
# the failure would only surface in the next step, as a traceback
# about a missing doc.json.
mkdir -p tools/docs/out
/tmp/luals/bin/lua-language-server \
--doc=lua \
--doc_out_path=tools/docs/out \
--configpath=tools/docs/luarc-docs.json \
--logpath=/tmp/luals-log
if [ ! -s tools/docs/out/doc.json ]; then
echo "::error::LuaLS exported no doc.json; see /tmp/luals-log"
exit 1
fi
-
name: Generate HTML Documentation
run: |
python3 tools/docs/generate.py \
--json tools/docs/out/doc.json \
--output tools/docs/build \
--style-dir tools/docs/style \
--topics docs \
--repo-ref "$GITHUB_SHA" \
--site-url "$SITE_URL"
-
name: Upload Built Docs
uses: actions/upload-artifact@v4
with:
name: docs-site
path: tools/docs/build/
# Only from development, which is what GitHub Pages serves. A push to
# master builds (so a docs break is caught there too) but must not
# publish: Pages serves one branch, and two would overwrite each other.
-
name: Deploy to GitHub Pages
if: github.event_name == 'push' && github.ref == 'refs/heads/development'
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./tools/docs/build
publish_branch: gh-pages
user_name: github-actions[bot]
user_email: 41898282+github-actions[bot]@users.noreply.github.com
commit_message: "docs: rebuild site for ${{ github.sha }}"
# Replace the branch outright rather than committing on top of it.
# The site is a full rebuild every run, so anything already on
# gh-pages that this build did not produce is stale by definition -
# a page whose module was renamed, a topic that moved into a folder,
# a previous build's content-hashed stylesheet. force_orphan also
# keeps the branch at a single commit, so the repository does not
# carry a full copy of the site for every push it has ever had.
force_orphan: true