No return code indicating failure

[dirk-thomas]

See ros-infrastructure/ros_buildfarm#284

@vrabaud FYI

[jack-oquin]

A test case or a pull request would expedite handling of this issue.

Is it just that any error or warning terminates with a zero return status?

[dirk-thomas]

I don't know about all cases but this specific case has a return code of zero.

[agutenkunst]

I really would like to see this feature. I think I could tackle this via:

if [ $(rosdoc_lite . 2>&1 >/dev/null | wc -l) != 0 ]; then echo "rosdoc fail"; else echo "success"; fi;

However there seems to be built-in errors as well.

Such as:

warning: Tag `XML_SCHEMA' at line 1796 of file `/tmp/tmptP6QDM' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag `XML_DTD' at line 1802 of file `/tmp/tmptP6QDM' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: tag INCLUDE_PATH: include path `$INCLUDE_PATH' does not exist
warning: source $INCLUDE_PATH is not a readable file or directory... skipping.

@tfoote any information?

[peci1]

Got hit by this now:

12:48:59 Invoking `rosdoc_lite` for package 'cras_py_common': python3 /tmp/rosdoc_lite/scripts/rosdoc_lite /tmp/ws/src/cras_ros_utils/cras_py_common -o /tmp/generated_documentation/api_rosdoc/cras_py_common -g /tmp/generated_documentation/symbols/cras_py_common.tag -t /tmp/generated_documentation/rosdoc_tags/cras_py_common.yaml
12:48:59 
12:49:00 Configuration error:
12:49:00 There is a programmable error in your configuration file:
12:49:00 
12:49:00 Traceback (most recent call last):
12:49:00   File "/usr/lib/python3/dist-packages/sphinx/config.py", line 368, in eval_config_file
12:49:00     execfile_(filename, namespace)
12:49:00   File "/usr/lib/python3/dist-packages/sphinx/util/pycompat.py", line 150, in execfile_
12:49:00     exec_(code, _globals)
12:49:00   File "/tmp/ws/src/cras_ros_utils/cras_py_common/doc/conf.py", line 5, in <module>
12:49:00     from cras_docs_common.sphinx_docs_conf import *
12:49:00   File "/tmp/ws/install_isolated/lib/python3/dist-packages/cras_docs_common/sphinx_docs_conf.py", line 139, in <module>
12:49:00     PyObject.doc_field_types[map(lambda f: f.name == 'variable', PyObject.doc_field_types).index(True)].rolename = None
12:49:00 AttributeError: 'map' object has no attribute 'index'
12:49:00 
12:49:00 Documenting a catkin package
12:49:00 Documenting cras_py_common located here: /tmp/ws/src/cras_ros_utils/cras_py_common
12:49:00 {'sphinx': {'builder': 'sphinx', 'sphinx_root_dir': 'doc'}}
12:49:00 Catkin package, no need to generate python paths
12:49:00 Sphinx python path is: /tmp/rosdoc_lite/src:/tmp/catkin-sphinx/src:/tmp/ws/install_isolated/lib/python3/dist-packages:/opt/ros/noetic/lib/python3/dist-packages:/tmp/ros_buildfarm
12:49:00 sphinx-building cras_py_common [sphinx-build -a -E -b html . /tmp/generated_documentation/api_rosdoc/cras_py_common/html/.]
12:49:00   cwd is /tmp/ws/src/cras_ros_utils/cras_py_common/doc
12:49:00 stdout:
12:49:00 b'Running Sphinx v1.8.5\n'
12:49:00 stderr
12:49:00 None
12:49:00 []
12:49:00 []
12:49:00 []

And buildfarm is happy... this really should not happen.

[tfoote]

This would be great to have. We've historically taken a relatively relaxed best effort approach for generating docs as we'd rather not discourage maintainers by spamming them all the time with failed doc builds, and the most common solution from them was to disable the builds. It's much more effective for users to report missing documentation to raise the maintainers attention.

Adding this capability would be great, then we could reconsider the buildfarm policy, and continue to ignore the errors or make it more strict going forward. But right now this is a backlog/help wanted status.

[peci1]

backlog/help wanted status

Does that mean PRs are welcome and will be considered in a reasonable timeframe? Or does it mean "sometime in the future"?

[tfoote]

Backlog means that we'd welcome this as an enhancement and will review PRs on it. But it's not planned to be picked up and worked on by the maintainers.

[peci1]

106 offers a potential solution to this issue.