Skip to content

update index file with and rst/md documents #99

update index file with and rst/md documents

update index file with and rst/md documents #99

Workflow file for this run

# Deploy Sphinx. This could be shorter, but we also do some extra
# stuff.
#
# License: CC-0. This is the canonical location of this file, which
# you may want to link to anyway:
# https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml
name: sphinx
on: [push, pull_request]
env:
DEFAULT_BRANCH: "main"
# If these SPHINXOPTS are enabled, then be strict about the
# builds and fail on any warnings.
#SPHINXOPTS: "-W --keep-going -T"
GENERATE_PDF: true # to enable, must be 'true' lowercase
GENERATE_SINGLEHTML: true # to enable, must be 'true' lowercase
PDF_FILENAME: lesson.pdf
MULTIBRANCH: true # to enable, must be 'true' lowercase
jobs:
build:
name: Build
runs-on: ubuntu-latest
permissions:
contents: read
steps:
# https://github.com/marketplace/actions/checkout
- uses: actions/checkout@v4
with:
fetch-depth: 0
lfs: true
# https://github.com/marketplace/actions/setup-python
# ^-- This gives info on matrix testing.
- name: Install Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
cache: 'pip'
# https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
# ^-- This gives info on installing dependencies with pip
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
# Debug
- name: Debugging information
env:
ref: ${{github.ref}}
event_name: ${{github.event_name}}
head_ref: ${{github.head_ref}}
base_ref: ${{github.base_ref}}
run: |
echo "github.ref: ${ref}"
echo "github.event_name: ${event_name}"
echo "github.head_ref: ${head_ref}"
echo "github.base_ref: ${base_ref}"
echo "GENERATE_PDF: ${GENERATE_PDF}"
echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}"
set -x
git rev-parse --abbrev-ref HEAD
git branch
git branch -a
git remote -v
python -V
pip list --not-required
pip list
# Build
- uses: ammaraskar/sphinx-problem-matcher@master
- name: Build Sphinx docs (dirhtml)
# SPHINXOPTS used via environment variables
run: |
make dirhtml
# This fixes broken copy button icons, as explained in
# https://github.com/coderefinery/sphinx-lesson/issues/50
# https://github.com/executablebooks/sphinx-copybutton/issues/110
# This can be removed once these PRs are accepted (but the
# fixes also need to propagate to other themes):
# https://github.com/sphinx-doc/sphinx/pull/8524
# https://github.com/readthedocs/sphinx_rtd_theme/pull/1025
sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true
# singlehtml
- name: Generate singlehtml
if: ${{ env.GENERATE_SINGLEHTML == 'true' }}
run: |
make singlehtml
mv _build/singlehtml/ _build/dirhtml/singlehtml/
# PDF if requested
- name: Generate PDF
if: ${{ env.GENERATE_PDF == 'true' }}
run: |
pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
make pyppeteer
mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME}
# Stage all deployed assets in _gh-pages/ for simplicity, and to
# prepare to do a multi-branch deployment.
- name: Copy deployment data to _gh-pages/
if: ${{ github.event_name == 'push' }}
run:
rsync -a _build/dirhtml/ _gh-pages/
# Use gh-pages-multibranch to multiplex different branches into
# one deployment. See
# https://github.com/coderefinery/gh-pages-multibranch
- name: gh-pages multibranch
uses: coderefinery/gh-pages-multibranch@main
if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }}
with:
directory: _gh-pages/
default_branch: ${{ env.DEFAULT_BRANCH }}
publish_branch: gh-pages
# Add the .nojekyll file
- name: nojekyll
if: ${{ github.event_name == 'push' }}
run: |
touch _gh-pages/.nojekyll
# Save artifact for the next step.
- uses: actions/upload-artifact@v4
if: ${{ github.event_name == 'push' }}
with:
name: gh-pages-build
path: _gh-pages/
# Deploy in a separate job so that write permissions are restricted
# to the minimum steps.
deploy:
name: Deploy
runs-on: ubuntu-latest
needs: build
# This if can't use the env context - find better way later.
if: ${{ github.event_name == 'push' }}
permissions:
contents: write
steps:
- uses: actions/download-artifact@v4
if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
with:
name: gh-pages-build
path: _gh-pages/
# As of 2023, we could publish to pages via a Deployment. This
# isn't done yet to give it time to stabilize (out of beta), and
# also having a gh-pages branch to check out is rather
# convenient.
# Deploy
# https://github.com/peaceiris/actions-gh-pages
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
with:
publish_branch: gh-pages
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: _gh-pages/
force_orphan: true