Skip to content

Commit ed0540b

Browse files
encukouhugovk
authored andcommitted
GHA, Docs: Add PR annotations for failed Sphinx references
1 parent f105fe4 commit ed0540b

File tree

2 files changed

+37
-0
lines changed

2 files changed

+37
-0
lines changed

.github/workflows/doc.yml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,19 @@ jobs:
5353
- name: 'Build HTML documentation'
5454
run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
5555

56+
# Add pull request annotations for Sphinx nitpicks (missing references)
57+
- name: Get list of changed files
58+
id: changed_files
59+
uses: jitterbit/get-changed-files@v1
60+
- name: 'Build with nitpicks'
61+
continue-on-error: true
62+
run: |
63+
# Mark files the pull request modified
64+
touch ${{ steps.changed_files.outputs.added_modified }}
65+
# Build docs with the '-n' (nitpicky) option, convert warnings
66+
make -C Doc/ PYTHON=../python SPHINXOPTS="-q --keep-going -n" html 2>&1 |
67+
python Doc/tools/warnings-to-gh-actions.py
68+
5669
# Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
5770
doctest:
5871
name: 'Doctest'

Doc/tools/warnings-to-gh-actions.py

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/usr/bin/env python3
2+
3+
"""Convert Sphinx warning messages to GitHub Actions
4+
5+
Converts lines like:
6+
.../Doc/library/cgi.rst:98: WARNING: reference target not found
7+
to:
8+
::warning file=.../Doc/library/cgi.rst,line=98::reference target not found
9+
10+
Non-matching lines are echoed unchanged.
11+
12+
see: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-a-warning-message
13+
"""
14+
15+
import sys
16+
import re
17+
18+
pattern = re.compile(r'(?P<file>[^:]+):(?P<line>\d+): WARNING: (?P<msg>.+)')
19+
20+
for line in sys.stdin:
21+
if match := pattern.fullmatch(line.strip()):
22+
print('::warning file={file},line={line}::{msg}'.format_map(match))
23+
else:
24+
print(line)

0 commit comments

Comments
 (0)