documentation build

[asmodehn]

Currently industrial_ci is testing build, run_tests, and install target.
It would be useful to include a doc build test, probably following the way the buildfarm does it, or something along the lines of http://wiki.ros.org/rosdoc_lite

[mathias-luedtke]

Do have an example that could be used to test such a feature?

I am not sure if the buildfarm doc scripts could be used like the prerelease script, i.e. to test the merged code.
Running rosdoc_lite for each package could be an alternative.

[asmodehn]

My most documented package is https://github.com/pyros-dev/catkin_pip/tree/industrial_ci. Doc has been generated there previously by the buildfarm : http://docs.ros.org/indigo/api/catkin_pip/html/.

I am currently migrating it to use industrial_ci instead of my custom travis and shell scripts, so we can use that package for testing it.

Using rosdoc_lite should be fine, thats what I usually do locally.

[asmodehn]

I recently made another package, much simpler, for testing this kind of thing : https://github.com/pyros-dev/ros1_template

[artivis]

Might be interesting to look at catkin_tools_document a catkin_tool plugin for building documentation at workspace-level.

[mathias-luedtke]

Thanks for pointing this out!
I have tried it, but I got stuck with #123 as doxgen writes temporary files to the src folder.
I will give it another try when I have more time.

[wxmerkt]

We have run into the same issue - beyond doxygen (which writes into the read-only source directory, but can be redirected) we run automatic documentation on a built Python module (bindings from C++), i.e., can only work if that build artefact is available. Is there any example for building documentation or work-around? (I have seen the open PR on making it write-able but it seems to not have been merged/gotten stuck).

[agutenkunst]

I would like to refresh this issue.

I recently added a rosdoc_lite check to our CI: PilzDE/psen_scan_v2@2d31822

It just validates that no warnings/errors are printed from rosdoc_lite. Unfortunately I had to filter some existing errors that would
need fixes upstream at rosdoc_lite see ros-infrastructure/rosdoc_lite#100

@ipa-mdl would you welcome a check for rosdoc_lite warnings/errors in industrial_ci?
I think it would fit in with CATKIN_LINT, CLANG_TIDY and PYLINT_CHECK.

[mathias-luedtke]

would you welcome a check for rosdoc_lite warnings/errors in industrial_ci?
I think it would fit in with CATKIN_LINT, CLANG_TIDY and PYLINT_CHECK.

Definitely!
I could imagine to have a standalone test for it (similar to https://github.com/ros-industrial/industrial_ci/blob/master/industrial_ci/src/tests/black_check.sh).
Something like "tests/doc.sh" (if we want to extend it later) or "tests/rosdoc_lite.sh" ?