stdout/stderr is missing when build fails due to unexpected return code

[ssbarnea]

At this moment, if documentation building is failing because one of the output commands is returning an unexpected exit code, we have no clue about what could have caused it as it lacks any other information.

Example:

Warning, treated as error:
Unexpected return code 1 from command 'yarnpkg --non-interactive --cwd=web run'
ERROR: InvocationError for command /home/ssbarnea/rmux/zuul/.tox/docs/bin/sphinx-build -E -W -d doc/build/doctrees -b html doc/source/ doc/build/html (exited with code 2)

Essential debugging info:

• [x] command line
• [ ] current working directory (can often impact the result)
• [ ] stdout
• [ ] stderr

It would extremely useful to include these missing bits when this happens, especially as running the same command outside sphinx may work. I should remark that I faced this issue on two different and unrelated projects, so is not really uncommon.

Please note that I would be happy to provide a pull-request that address this issue, but I would like to hear the maintainer opinion before doing the work to implement that, especially as the current implementation is using a tuple to return results, something that is not really nice/easy to extend.

Currently something like (result, output) is passed across several functions and adding cwd would make it look like result, output, cwd). That is one moment where you realised that using a CompletedProcess produced by subprocess.run would have being much nicer.

[jamadden]

Thanks for the suggestions. I've implemented them in #53.

[joshuacwnewton]

Thanks for adding this!

Unexpected return code 1 from command 'yarnpkg --non-interactive --cwd=web run'

I'm currently running into this exact same error message on RTD. The timing seems like just a coincidence, but providing stdout/stderr would be a big boon, so thank you. :smile:

[ssbarnea]

@joshuacwnewton It gets even more interesting because I got into a case where a command works when run locally but fails under sphinx and I suspected that cwd feature was not working as expected. Still, based on tests I done with running pwd it seems that cwd feature is working as it should for both program and command output.

Once this fix goes out we can start injecting other debugging commands and narrow down what causes the CI to fail in cryptic way.

[jamadden]

This has been released to PyPI. It was in time to catch the errors from the CI runs of @joshuacwnewton : There's an import error.

WARNING: Unexpected return code 1 from command Command(command=('sct_analyze_lesion', '-h'), shell=False, hide_standard_error=False, working_directory='/home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/checkouts/3317/documentation/source') (output='Traceback (most recent call last):\n  File "/home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/envs/3317/lib/python3.6/site-packages/spinalcordtoolbox/scripts/sct_analyze_lesion.py", line 21, in <module>\n    from spinalcordtoolbox.image import Image\n  File "/home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/envs/3317/lib/python3.6/site-packages/spinalcordtoolbox/image.py", line 26, in <module>\n    from contrib import fslhd\nModuleNotFoundError: No module named \'contrib\'')

That is,

Traceback (most recent call last):
  File "/.../lib/python3.6/site-packages/spinalcordtoolbox/scripts/sct_analyze_lesion.py", line 21, in <module>
    from spinalcordtoolbox.image import Image
  File "/.../lib/python3.6/site-packages/spinalcordtoolbox/image.py", line 26, in <module>
    from contrib import fslhd
ModuleNotFoundError: No module named 'contrib'

[joshuacwnewton]

Not only have you addressed this request, but you've debugged my issue, too! Thank you. :wink: