doc: move docgen filter out of shippable script
Because of known issues with Sphinx/Breathe tools we're using to generate doxygen-based comments for our API documentation, we're getting a bevy of warning messages written out. As a workaround for our CI system, we created a filter-known-issues.py script to remove "expected" warnings from the output. This patch moves calling that filter script into the doc generation Makefile so folks making local builds of the docs won't be tripped up by all the warning messages either. Output of the "make htmldocs" command is now filtered so only "unexpected" errors and warnings will be shown. (See https://github.com/sphinx-doc/sphinx/issue/2682 and sphinx-doc/sphinx#2683i for the Sphinx/Breathe issues.) Fixes #1527 Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
parent
ae76cb0598
commit
d3b0cd4827
3 changed files with 30 additions and 9 deletions
|
@ -40,17 +40,11 @@ build:
|
|||
echo "Building a Pull Request";
|
||||
echo "- Building Documentation";
|
||||
echo "Commit range:" ${COMMIT_RANGE}
|
||||
make htmldocs > doc.log 2>&1;
|
||||
./scripts/filter-known-issues.py --config-dir .known-issues/doc/ doc.log > doc.warnings;
|
||||
|
||||
if [ "$?" != 0 ]; then
|
||||
echo " ==> Error running filter script"
|
||||
exit 1
|
||||
fi;
|
||||
make htmldocs > doc.warnings 2>&1;
|
||||
if [ -s doc.warnings ]; then
|
||||
echo " => New documentation warnings/errors";
|
||||
fi;
|
||||
echo "- Verify commit message and coding style";
|
||||
echo "- Verify commit message, coding style, doc build";
|
||||
./scripts/ci/check-compliance.py --commits ${COMMIT_RANGE} || true;
|
||||
fi;
|
||||
- >
|
||||
|
|
|
@ -79,7 +79,8 @@ kconfig: scripts/genrest/genrest.py
|
|||
prep: doxy content kconfig
|
||||
|
||||
html: content kconfig
|
||||
$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html > doc.log 2>&1;
|
||||
$(Q)./scripts/filter-doc-log.sh doc.log
|
||||
@rm -rf samples
|
||||
@rm -rf boards
|
||||
|
||||
|
|
26
doc/scripts/filter-doc-log.sh
Executable file
26
doc/scripts/filter-doc-log.sh
Executable file
|
@ -0,0 +1,26 @@
|
|||
#!/bin/bash
|
||||
|
||||
# run the filter-known-issues.py script to remove "expected" warning
|
||||
# messages from the output of the document build process and write
|
||||
# the filtered output to stdout
|
||||
#
|
||||
# Only argument is the name of the log file saved by the build.
|
||||
|
||||
KI_SCRIPT=${ZEPHYR_BASE}/scripts/filter-known-issues.py
|
||||
CONFIG_DIR=${ZEPHYR_BASE}/.known-issues/doc
|
||||
|
||||
LOG_FILE=$1
|
||||
|
||||
if [ -z "${LOG_FILE}" ]; then
|
||||
echo "Error in $0: missing input parameter <logfile>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ -e "${LOG_FILE}" ]; then
|
||||
if [ -s "${LOG_FILE}" ]; then
|
||||
$KI_SCRIPT --config-dir ${CONFIG_DIR} ${LOG_FILE}
|
||||
fi
|
||||
else
|
||||
echo "Error in $0: logfile \"${LOG_FILE}\" not found."
|
||||
exit 1
|
||||
fi
|
Loading…
Add table
Add a link
Reference in a new issue