I was running "make suspicious" in Doc/ and this was the output after finding 3 suspicious markups:

 writing output... [ 52%] library/inspect
 WARNING: [library/inspect:437] ":int" found in ">>> def foo(a, *, b:int, **kwargs):"
 WARNING: [library/inspect:437] ":int" found in "'(a, *, b:int, **kwargs)'"
 WARNING: [library/inspect:437] ":int" found in "'b:int'"
 writing output... [100%] whatsnew/index
 build finished with problems, 3 warnings.
 make: *** [build] Error 1

After figuring out how to mark these as false positives and adding the relevant entries to susp-ignored.csv, I ran "make suspicious" again, and got this useful message at the end:

writing output... [100%] whatsnew/index
build succeeded.

Suspicious check complete; look for any errors in the above output or in build/suspicious /suspicious.csv. If all issues are false positives, append that file to tools/sphinxext/susp-ignored.csv.

The problem is that this message should be displayed when there are failures, but it's not.

Attached an attempt to fix the Makefile to avoid exiting in case of failures when the builder is "suspicious". Given that I'm not really familiar with makefiles, it probably doesn't make much sense.

Apparently a '-' at the beginning of the command means "run this thing and if it fails ignore the failure and keep going". I tried to add an if/else in the build target to use the '-' with the selected builder was "suspicious" but I couldn't make it work, so I ended up adding a new build-and-continue that uses the '-'.

make linkcheck and make doctest had the same problem, so I fixed them too.

The output now looks like this:

$ make suspicious
mkdir -p build/suspicious build/doctrees
python tools/sphinx-build.py -b suspicious -d build/doctrees -D latex_paper_size=  . build/suspicious 
Running Sphinx v1.0.7
loading pickled environment... done
loading ignore rules... done, 359 rules loaded
building [suspicious]: targets for 428 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [ 81%] library/unittest
WARNING: [library/unittest:19] ":port" found in "host:port"
writing output... [100%] whatsnew/index
build finished with problems, 1 warning.
make: [build-and-continue] Error 1 (ignored)

Suspicious check complete; look for any errors in the above output or in build/suspicious/suspicious.csv. If all issues are false positives, append that file to tools/sphinxext/susp-ignored.csv.

The error exit code should be preserved though.

I nominate this text:

To make these errors go away, merge the contents of "build/suspicious/suspicious.csv" to "tools/sphinxext/susp-ignored.csv".

Alternatively, we could add a "make trustworthy" target that did this work automatically, in which case the text should be

To make these errors go away, run "make trustworthy".

Since Ezio asked me, I guess I wasn't clear:

This message should be displayed at the bottom, after the errors, and only when there are alleged suspicious documentation activities.

Try this patch.

Looks good. Maybe Larry will want his line of stars though :)

Can we use unicode characters? I'd like little ships, or U+1F4A9.

It was not such good. Here is better patch.

Serhiy, your patch LGTM.
Can you apply a similar fix for the linkcheck and doctest target and commit it?

FWIW the patch produces a slightly different output (in addition to showing the missing message), but I don't think it's a problem:
Without patch:
...
build finished with problems, 8 warnings.
make: *** [build] Error 1
With patch:
...
build finished with problems, 8 warnings.
make[1]: *** [build] Error 1
make[1]: Leaving directory `/home/wolf/dev/py/py3k/Doc'
Suspicious check complete; ...
make: *** [suspicious] Error 1

Oh, I forgot about this patch.

Here is more correct patch. It now works with non-default make command and "make suspicious" now returns success return code if no suspicious markups were found. Made similar fix for the linkcheck and doctest target.

New changeset 10b83036c723 by Serhiy Storchaka in branch '3.4':
Issue bpo-15759: "make suspicious", "make linkcheck" and "make doctest" in Doc/
http://hg.python.org/cpython/rev/10b83036c723

New changeset c755a3b58fa6 by Serhiy Storchaka in branch 'default':
Issue bpo-15759: "make suspicious", "make linkcheck" and "make doctest" in Doc/
http://hg.python.org/cpython/rev/c755a3b58fa6

New changeset a61c3d17fe4f by Serhiy Storchaka in branch '2.7':
Issue bpo-15759: "make suspicious", "make linkcheck" and "make doctest" in Doc/
http://hg.python.org/cpython/rev/a61c3d17fe4f

Thanks for fixing this!