Merge branch 'bugfix/ci_sphinx_warnings' into 'master'
ci: Add new check_doc_warnings.sh script, pre-process log lines See merge request !1258
This commit is contained in:
commit
ad0d30302b
4 changed files with 65 additions and 17 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
@ -27,6 +27,7 @@ examples/**/build
|
||||||
docs/_build/
|
docs/_build/
|
||||||
docs/doxygen-warning-log.txt
|
docs/doxygen-warning-log.txt
|
||||||
docs/sphinx-warning-log.txt
|
docs/sphinx-warning-log.txt
|
||||||
|
docs/sphinx-warning-log-sanitized.txt
|
||||||
docs/xml/
|
docs/xml/
|
||||||
docs/man/
|
docs/man/
|
||||||
|
|
||||||
|
|
|
@ -179,6 +179,7 @@ build_docs:
|
||||||
paths:
|
paths:
|
||||||
- docs/doxygen-warning-log.txt
|
- docs/doxygen-warning-log.txt
|
||||||
- docs/sphinx-warning-log.txt
|
- docs/sphinx-warning-log.txt
|
||||||
|
- docs/sphinx-warning-log-sanitized.txt
|
||||||
- docs/_build/html
|
- docs/_build/html
|
||||||
expire_in: 1 mos
|
expire_in: 1 mos
|
||||||
script:
|
script:
|
||||||
|
@ -188,18 +189,7 @@ build_docs:
|
||||||
- test $(cat doxygen-warning-log.txt | wc -l) -eq 0 || ( echo "Doxygen pass had some warnings:" && cat doxygen-warning-log.txt && false )
|
- test $(cat doxygen-warning-log.txt | wc -l) -eq 0 || ( echo "Doxygen pass had some warnings:" && cat doxygen-warning-log.txt && false )
|
||||||
- make gh-linkcheck
|
- make gh-linkcheck
|
||||||
- make html
|
- make html
|
||||||
# If there are Sphinx warnings, print them and bail out
|
- ./check_doc_warnings.sh
|
||||||
# Ignore warnings (sphinx-known-warnings.txt) already reported in:
|
|
||||||
# https://github.com/sphinx-doc/sphinx/issues/2683
|
|
||||||
# https://github.com/sphinx-doc/sphinx/issues/4041
|
|
||||||
# If a new warning has to be added, then it should be documented as above
|
|
||||||
# Note: this check is not clever enough to ignore the same warning
|
|
||||||
# but reported for different line of documentation.
|
|
||||||
# If s warning stays the same and the line number has changed,
|
|
||||||
# then update 'sphinx-known-warnings.txt' to reflect the new lines numbers.
|
|
||||||
- DIFF_FORMAT="--changed-group-format=%<%> --unchanged-group-format="
|
|
||||||
- LOG_DIFF=$(diff $DIFF_FORMAT sphinx-known-warnings.txt sphinx-warning-log.txt)
|
|
||||||
- test -z "$LOG_DIFF" || ( echo "Sphinx pass had some new warnings:" && echo "$LOG_DIFF" && false )
|
|
||||||
|
|
||||||
test_nvs_on_host:
|
test_nvs_on_host:
|
||||||
stage: test
|
stage: test
|
||||||
|
|
41
docs/check_doc_warnings.sh
Executable file
41
docs/check_doc_warnings.sh
Executable file
|
@ -0,0 +1,41 @@
|
||||||
|
#!/bin/bash
|
||||||
|
#
|
||||||
|
# Check for Documentation warnings:
|
||||||
|
# doxygen-warning-log.txt should be an empty file
|
||||||
|
# sphinx-warning-log.txt should only contain (fuzzy) matches to sphinx-known-warnings.txt
|
||||||
|
cd "$(dirname $0)"
|
||||||
|
RESULT=0
|
||||||
|
STARS='***************************************************'
|
||||||
|
|
||||||
|
if [ -s doxygen-warning-log.txt ]; then
|
||||||
|
echo "$STARS"
|
||||||
|
echo "Build failed due to doxygen warnings:"
|
||||||
|
cat doxygen-warning-log.txt
|
||||||
|
echo "$STARS"
|
||||||
|
RESULT=1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Remove escape characters, file paths, line numbers from
|
||||||
|
# the Sphinx warning log
|
||||||
|
# (escape char removal from https://www.commandlinefu.com/commands/view/6141/remove-color-codes-special-characters-with-sed
|
||||||
|
sed -r 's:\x1B\[[0-9;]*[mK]::g' sphinx-warning-log.txt | \
|
||||||
|
sed -E "s~${IDF_PATH}~\${IDF_PATH}~" | \
|
||||||
|
sed -E "s/:[0-9]+:/:line:/" > sphinx-warning-log-sanitized.txt
|
||||||
|
|
||||||
|
# diff sanitized warnings, ignoring lines which only appear in sphinx-known-warnings.txt
|
||||||
|
|
||||||
|
# format is to display only lines new or changed in second argument
|
||||||
|
DIFF_FORMAT="--unchanged-line-format= --old-line-format= --new-line-format=%L"
|
||||||
|
|
||||||
|
SPHINX_WARNINGS=$(diff $DIFF_FORMAT sphinx-known-warnings.txt sphinx-warning-log-sanitized.txt)
|
||||||
|
if ! [ -z "$SPHINX_WARNINGS" ]; then
|
||||||
|
echo "$STARS"
|
||||||
|
echo "Build failed due to new/different Sphinx warnings:"
|
||||||
|
echo "$SPHINX_WARNINGS"
|
||||||
|
echo "$STARS"
|
||||||
|
RESULT=1
|
||||||
|
echo "(Check files sphinx-known-warnings.txt and sphinx-warning-log.txt for full details.)"
|
||||||
|
fi
|
||||||
|
|
||||||
|
exit $RESULT
|
||||||
|
|
|
@ -1,9 +1,25 @@
|
||||||
_build/inc/esp_a2dp_api.inc:26: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
|
# File contains known/allowed Sphinx warnings.
|
||||||
|
#
|
||||||
|
# Build will fail if sphinx-warning-log.txt contains any lines
|
||||||
|
# which are not in this file. Lines are pre-sanitized by
|
||||||
|
# check_doc_warnings.sh to remove formatting, paths, line numbers.
|
||||||
|
#
|
||||||
|
# Warnings in this file must be in the same overall order as the log file.
|
||||||
|
#
|
||||||
|
|
||||||
|
#
|
||||||
|
# Sphinx known issue https://github.com/sphinx-doc/sphinx/issues/2683\
|
||||||
|
#
|
||||||
|
_build/inc/esp_a2dp_api.inc:line: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
|
||||||
union esp_a2d_mcc_t::@1 esp_a2d_mcc_t::cie
|
union esp_a2d_mcc_t::@1 esp_a2d_mcc_t::cie
|
||||||
---------------------^
|
---------------------^
|
||||||
_build/inc/esp_bt_defs.inc:11: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
|
_build/inc/esp_bt_defs.inc:line: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
|
||||||
union esp_bt_uuid_t::@0 esp_bt_uuid_t::uuid
|
union esp_bt_uuid_t::@0 esp_bt_uuid_t::uuid
|
||||||
---------------------^
|
---------------------^
|
||||||
/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
|
|
||||||
/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
|
#
|
||||||
/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
|
# Sphinx known issue https://github.com/sphinx-doc/sphinx/issues/4041
|
||||||
|
#
|
||||||
|
${IDF_PATH}/docs/api-reference/storage/sdmmc.rst:line: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
|
||||||
|
${IDF_PATH}/docs/api-reference/storage/sdmmc.rst:line: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
|
||||||
|
${IDF_PATH}/docs/api-reference/storage/sdmmc.rst:line: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
|
||||||
|
|
Loading…
Reference in a new issue