sphinx-doc / sphinx-doc/sphinx

Feature request: Summarise all errors/warnings when exiting

Open
#10,307 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:proposal
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.
When sphinx-build is run with options -W --keep-going, the errors (that are correctly handled as warnings) appears in the output, but are not summarised at the end, once the process does exit with e.g. exit code 2.

Describe the solution you'd like
A summary of the errors/warnings that have caused the non-zero exit code, e.g. re-listed each of them after this line:
build finished with problems, 2 warnings.

Describe alternatives you've considered
My current workaround is to redirect stderr to a temporary file, and then output that if the exit code is non-zero, e.g.

make BUILDDIR="$AGENT_BUILDDIRECTORY" html 2> $AGENT_BUILDDIRECTORY/build-docs-make-stderr.log
make_return_value=$?
if [ $make_return_value -ne 0 ]; then
    echo ""
    echo "Summary of errors from the make / sphinx-build process:"
    cat $AGENT_BUILDDIRECTORY/build-docs-make-stderr.log 2> /dev/null
    exit $make_return_value
fi

This gives me something like:

build finished with problems, 2 warnings.

Summary of errors from the make / sphinx-build process:
/opt/azdo-agent/_work/1/s/CONTRIBUTING.md:6: WARNING: 'myst' reference target not found: content-owners.md
/opt/azdo-agent/_work/1/s/CONTRIBUTING.md:15: WARNING: 'myst' reference target not found: content-owners.md
make: *** [Makefile:35: html] Error 1

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the sphinx-build command path for -W --keep-going and the existing final "build finished with problems" output. No source files or tests are named in the issue, so locate the warning collection and its exit-status handling first. Done means the relevant errors or warnings are summarized at exit while preserving the non-zero status.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.