Skip to content

Commit 229724b

Browse files
felixfonteinfelixfontein
authored
Support new antsibull-docs sphinx-init options. (#65)
1 parent 413f295 commit 229724b

File tree

4 files changed

+298
-5
lines changed

4 files changed

+298
-5
lines changed

‎.github/workflows/_shared-docs-build-pr.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,52 @@ on:
5353
required: false
5454
type: string
5555
default: ansible-community/antsibull-docs
56+
init-index-rst-source:
57+
description: |
58+
Copy the provided file to `rst/index.rst` intead of templating a default one.
59+
required: false
60+
type: string
61+
init-project:
62+
description: |
63+
Sets the `project` value in the Sphinx configuration.
64+
required: false
65+
type: string
66+
init-copyright:
67+
description: |
68+
Sets the `copyright` value in the Sphinx configuration.
69+
required: false
70+
type: string
71+
init-title:
72+
description: |
73+
Sets the `title` and `html_short_title` values in the Sphinx configuration.
74+
If `init-html-short-title` is also specified, only `title` will be set to the value
75+
specified here.
76+
required: false
77+
type: string
78+
init-html-short-title:
79+
description: |
80+
Sets the `html_short_title` value in the Sphinx configuration. If not specified,
81+
the value of `init-title` will be used.
82+
required: false
83+
type: string
84+
init-extra-conf:
85+
description: |
86+
A newline separated list of `key=value` entries that will be added to the generated
87+
`conf.py`.
88+
required: false
89+
type: string
90+
init-extra-html-context:
91+
description: |
92+
A newline separated list of `key=value` entries that will be added to the generated
93+
`conf.py` in `html_context`
94+
required: false
95+
type: string
96+
init-extra-html-theme-options:
97+
description: |
98+
A newline separated list of `key=value` entries that will be added to the generated
99+
`conf.py` in `html_theme_options`
100+
required: false
101+
type: string
56102
artifact-name:
57103
description: The name of the artifact to upload.
58104
required: false
@@ -258,6 +304,14 @@ jobs:
258304
provide-link-targets: ${{ inputs.provide-link-targets }}
259305
intersphinx-links: ${{ inputs.intersphinx-links }}
260306
squash-hierarchy: ${{ inputs.squash-hierarchy }}
307+
index-rst-source: ${{ inputs.init-index-rst-source }}
308+
project: ${{ inputs.init-project }}
309+
copyright: ${{ inputs.init-copyright }}
310+
title: ${{ inputs.init-title }}
311+
html-short-title: ${{ inputs.init-html-short-title }}
312+
extra-conf: ${{ inputs.init-extra-conf }}
313+
extra-html-context: ${{ inputs.init-extra-html-context }}
314+
extra-html-theme-options: ${{ inputs.init-extra-html-theme-options }}
261315

262316
- name: Build BASE
263317
id: build-base
@@ -294,6 +348,14 @@ jobs:
294348
provide-link-targets: ${{ inputs.provide-link-targets }}
295349
intersphinx-links: ${{ inputs.intersphinx-links }}
296350
squash-hierarchy: ${{ inputs.squash-hierarchy }}
351+
index-rst-source: ${{ inputs.init-index-rst-source }}
352+
project: ${{ inputs.init-project }}
353+
copyright: ${{ inputs.init-copyright }}
354+
title: ${{ inputs.init-title }}
355+
html-short-title: ${{ inputs.init-html-short-title }}
356+
extra-conf: ${{ inputs.init-extra-conf }}
357+
extra-html-context: ${{ inputs.init-extra-html-context }}
358+
extra-html-theme-options: ${{ inputs.init-extra-html-theme-options }}
297359

298360
- name: Build HEAD
299361
id: build-head

‎.github/workflows/_shared-docs-build-push.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,52 @@ on:
5555
required: false
5656
type: string
5757
default: ansible-community/antsibull-docs
58+
init-index-rst-source:
59+
description: |
60+
Copy the provided file to `rst/index.rst` intead of templating a default one.
61+
required: false
62+
type: string
63+
init-project:
64+
description: |
65+
Sets the `project` value in the Sphinx configuration.
66+
required: false
67+
type: string
68+
init-copyright:
69+
description: |
70+
Sets the `copyright` value in the Sphinx configuration.
71+
required: false
72+
type: string
73+
init-title:
74+
description: |
75+
Sets the `title` and `html_short_title` values in the Sphinx configuration.
76+
If `init-html-short-title` is also specified, only `title` will be set to the value
77+
specified here.
78+
required: false
79+
type: string
80+
init-html-short-title:
81+
description: |
82+
Sets the `html_short_title` value in the Sphinx configuration. If not specified,
83+
the value of `init-title` will be used.
84+
required: false
85+
type: string
86+
init-extra-conf:
87+
description: |
88+
A newline separated list of `key=value` entries that will be added to the generated
89+
`conf.py`.
90+
required: false
91+
type: string
92+
init-extra-html-context:
93+
description: |
94+
A newline separated list of `key=value` entries that will be added to the generated
95+
`conf.py` in `html_context`
96+
required: false
97+
type: string
98+
init-extra-html-theme-options:
99+
description: |
100+
A newline separated list of `key=value` entries that will be added to the generated
101+
`conf.py` in `html_theme_options`
102+
required: false
103+
type: string
58104
artifact-upload:
59105
description: Whether or not to upload the build as an artifact.
60106
type: boolean
@@ -176,6 +222,14 @@ jobs:
176222
provide-link-targets: ${{ inputs.provide-link-targets }}
177223
intersphinx-links: ${{ inputs.intersphinx-links }}
178224
squash-hierarchy: ${{ inputs.squash-hierarchy }}
225+
index-rst-source: ${{ inputs.init-index-rst-source }}
226+
project: ${{ inputs.init-project }}
227+
copyright: ${{ inputs.init-copyright }}
228+
title: ${{ inputs.init-title }}
229+
html-short-title: ${{ inputs.init-html-short-title }}
230+
extra-conf: ${{ inputs.init-extra-conf }}
231+
extra-html-context: ${{ inputs.init-extra-html-context }}
232+
extra-html-theme-options: ${{ inputs.init-extra-html-theme-options }}
179233

180234
- name: Build
181235
id: build

‎.github/workflows/test-action-build-init.yml‎

Lines changed: 80 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,22 @@ jobs:
4343
- |
4444
outside_reference_1
4545
outside_reference_2
46+
index-rst-source:
47+
- ''
48+
project:
49+
- ''
50+
copyright:
51+
- ''
52+
title:
53+
- ''
54+
html-short-title:
55+
- ''
56+
extra-conf:
57+
- ''
58+
extra-html-context:
59+
- ''
60+
extra-html-theme-options:
61+
- ''
4662
intersphinx-links: ['']
4763
squash-hierarchy:
4864
- false
@@ -61,12 +77,29 @@ jobs:
6177
amazon_aws:https://ansible-collections.github.io/amazon.aws/branch/main/
6278
ansible_devel:https://docs.ansible.com/ansible-core/devel/
6379
squash-hierarchy: false
80+
index-rst-source: README.md
81+
title: Some long title
6482
- skip-init: false
6583
collections: foo.bar
6684
dest: ''
6785
lenient: false
6886
fail-on-error: true
6987
squash-hierarchy: true
88+
project: Foo
89+
copyright: Bar
90+
title: Long title
91+
html-short-title: Short title
92+
extra-conf: |
93+
foo=bar
94+
baz=bam
95+
long=This is "something long" 'with different quotes'
96+
extra-html-context: |
97+
foo=bam
98+
baz=bar
99+
long=Another "long" 'quotes' sentence
100+
extra-html-theme-options: |
101+
foo=baz
102+
long=Yet "another" long 'quotes' text
70103
71104
steps:
72105
- name: Checkout
@@ -96,6 +129,14 @@ jobs:
96129
provide-link-targets: ${{ matrix.provide-link-targets }}
97130
intersphinx-links: ${{ matrix.intersphinx-links }}
98131
squash-hierarchy: ${{ matrix.squash-hierarchy }}
132+
index-rst-source: ${{ matrix.index-rst-source }}
133+
project: ${{ matrix.project }}
134+
copyright: ${{ matrix.copyright }}
135+
title: ${{ matrix.title }}
136+
html-short-title: ${{ matrix.html-short-title }}
137+
extra-conf: ${{ matrix.extra-conf }}
138+
extra-html-context: ${{ matrix.extra-html-context }}
139+
extra-html-theme-options: ${{ matrix.extra-html-theme-options }}
99140

100141
- name: assert
101142
env:
@@ -104,6 +145,8 @@ jobs:
104145
run: |
105146
set -x
106147
148+
ORIGINAL_DIR=$(pwd)
149+
107150
# check that the build script exists
108151
[ -f "$output_build_script" ] || exit 1
109152
@@ -112,11 +155,30 @@ jobs:
112155
mkdir -p "$output_build_html"
113156
cd "$output_build_html/../.."
114157
158+
${{ matrix.skip-init }} || (
159+
echo "::group::Show requirements.txt contents"
160+
cat requirements.txt
161+
echo
162+
echo "::endgroup::"
163+
164+
echo "::group::Show build.sh contents"
165+
cat build.sh
166+
echo
167+
echo "::endgroup::"
168+
169+
echo "::group::Show conf.py contents"
170+
cat conf.py
171+
echo
172+
echo "::endgroup::"
173+
)
174+
115175
# by now, all requirements should have been installed, let's pip freeze
116176
pip freeze > "${{ runner.temp }}/pre-freeze.txt"
117177
118178
# now we'll try to do a pip install again with the requirements file
179+
echo "::group::Install requirements again"
119180
pip install -r "requirements.txt" --disable-pip-version-check
181+
echo "::endgroup::"
120182
121183
# and pip freeze again to compare
122184
pip freeze > "${{ runner.temp }}/post-freeze.txt"
@@ -153,6 +215,23 @@ jobs:
153215
# Check that the squash hierarchy flag was added
154216
${{ matrix.squash-hierarchy }} && (grep -q -- ' --squash-hierarchy ' build.sh || exit 1)
155217
156-
# check if provide-link-targets was not used when being empty
218+
# Check if provide-link-targets was not used when being empty
157219
# short circuit if skip-init is 'true' or matrix.provide-link-targets is not empty
158220
${{ matrix.skip-init }} || ${{ matrix.provide-link-targets != '' }} || ! test -e rst/_targets.rst || exit 1
221+
222+
# Check whether index-rst-source worked
223+
${{ matrix.index-rst-source && 'true' || 'false' }} && (diff "${ORIGINAL_DIR}/${{ matrix.index-rst-source }}" rst/index.rst || exit 1)
224+
225+
# Check whether config options worked
226+
${{ matrix.project && 'true' || 'false' }} && (grep "project = '${{ matrix.project }}'" conf.py || exit 1)
227+
${{ matrix.copyright && 'true' || 'false' }} && (grep "copyright = '${{ matrix.copyright }}'" conf.py || exit 1)
228+
${{ matrix.title && 'true' || 'false' }} && (grep "title = '${{ matrix.title }}'" conf.py || exit 1)
229+
${{ matrix.title && !matrix.html-short-title && 'true' || 'false' }} && (grep "html_short_title = '${{ matrix.title }}'" conf.py || exit 1)
230+
${{ matrix.html-short-title && 'true' || 'false' }} && (grep "html_short_title = '${{ matrix.html-short-title }}'" conf.py || exit 1)
231+
232+
# TODO Check extra-conf
233+
# TODO Check extra-html-context
234+
# TODO Check extra-html-theme-options
235+
236+
# This must be the last line
237+
exit 0

0 commit comments

Comments
 (0)