generated from ENCCS/sphinx-lesson-template
-
Notifications
You must be signed in to change notification settings - Fork 0
170 lines (149 loc) · 5.82 KB
/
sphinx.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
# 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
# https://raw.githubusercontent.com/coderefinery/sphinx-lesson-template/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