classification
Title: "make suspicious" doesn't display instructions in case of failure
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.5, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: serhiy.storchaka Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, larry, python-dev, serhiy.storchaka
Priority: normal Keywords: easy, patch

Created on 2012-08-22 05:34 by ezio.melotti, last changed 2014-08-05 05:02 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue15759.diff ezio.melotti, 2012-08-22 05:34 Attempt to fix the Makefile. review
issue15759-2.diff ezio.melotti, 2012-09-21 18:49 review
make_suspicious.patch serhiy.storchaka, 2014-01-26 14:03 review
make_suspicious_2.patch serhiy.storchaka, 2014-07-08 14:46 review
Messages (13)
msg168842 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-08-22 05:34
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.
msg170910 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-21 18:49
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.
msg170956 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-09-22 06:51
The error exit code should be preserved though.
msg209297 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2014-01-26 11:43
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".
**********************************************************************
msg209299 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2014-01-26 12:12
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.
msg209309 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-01-26 13:31
Try this patch.
msg209310 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-26 13:43
Looks good. Maybe Larry will want his line of stars though :)
msg209316 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2014-01-26 14:03
Can we use unicode characters?  I'd like little ships, or U+1F4A9.
msg209317 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-01-26 14:03
It was not such good. Here is better patch.
msg222560 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-07-08 14:00
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
msg222565 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-07-08 14:46
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.
msg223644 - (view) Author: Roundup Robot (python-dev) Date: 2014-07-22 08:05
New changeset 10b83036c723 by Serhiy Storchaka in branch '3.4':
Issue #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 #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 #15759: "make suspicious", "make linkcheck" and "make doctest" in Doc/
http://hg.python.org/cpython/rev/a61c3d17fe4f
msg224805 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-08-05 05:02
Thanks for fixing this!
History
Date User Action Args
2014-08-05 05:02:48ezio.melottisetmessages: + msg224805
2014-07-22 08:36:49serhiy.storchakasetstatus: open -> closed
assignee: docs@python -> serhiy.storchaka
resolution: fixed
stage: patch review -> resolved
2014-07-22 08:05:54python-devsetnosy: + python-dev
messages: + msg223644
2014-07-08 14:46:12serhiy.storchakasetfiles: + make_suspicious_2.patch

messages: + msg222565
2014-07-08 14:00:53ezio.melottisetmessages: + msg222560
versions: + Python 3.5, - Python 3.3
2014-01-26 14:03:22serhiy.storchakasetfiles: - make_suspicious.patch
2014-01-26 14:03:10serhiy.storchakasetfiles: + make_suspicious.patch

messages: + msg209317
2014-01-26 14:03:07larrysetmessages: + msg209316
2014-01-26 13:43:37georg.brandlsetmessages: + msg209310
2014-01-26 13:31:16serhiy.storchakasetfiles: + make_suspicious.patch
nosy: + serhiy.storchaka
messages: + msg209309

2014-01-26 12:12:08larrysetmessages: + msg209299
2014-01-26 11:43:35larrysetnosy: + larry
messages: + msg209297
2013-11-24 15:19:18ezio.melottisetkeywords: + easy
stage: commit review -> patch review
versions: + Python 3.4, - Python 3.2
2012-09-22 06:51:41georg.brandlsetmessages: + msg170956
2012-09-21 18:49:49ezio.melottisetfiles: + issue15759-2.diff

stage: patch review -> commit review
messages: + msg170910
versions: + Python 2.7, Python 3.2
2012-08-22 05:34:23ezio.melotticreate