Generate documentation for workspace?

[mikepurvis]

I would like to be able to run rosdoc_lite across a workspace, generating docs for each package into a "doc space". I want the packages to be built in dependency order, supplying each one with a yaml pointing to the tags files of everything it depends on.

It seems fairly clear that this shouldn't be first class functionality of catkin_tools, but I feel like there are a bunch of pieces of c_t that I could possibly take advantage of in building it (dependency resolution, build order, parallel execution engine, etc).

So my question is: how realistic would it be to make a plugin build_docs verb which calls a bunch of the same execute_jobs logic, but feeds it a separate Job/Stage configuration which builds docs rather than binaries? I think for sanity, there'd have to be a base expectation that the environment from which catkin build_docs is called is a result space already containing catkin, genmsg, and rosdoc_lite. So the docs verb is only concerned with building docs, not also building the dependencies required to build docs.

Anyway, thoughts?

[mikepurvis]

Related: ros-infrastructure/rosdoc_lite#66

[mikepurvis]

This is a super-naive bash implementation of what I want to do more efficiently and fault-tolerantly using catkin_tools:

#!/bin/bash

mkdir -p docs
echo "" > docs/tags.yaml

for PKG_PATH in $(catkin_topological_order --only-folders src); do
  PKG=$(basename ${PKG_PATH})
  rosdoc_lite -t docs/tags.yaml -g docs/${PKG}/${PKG}.tag -o docs/${PKG} src/${PKG_PATH}
  echo "- docs_url: file://$(pwd)/docs/${PKG}/html" >> docs/tags.yaml
  echo "  location: file://$(pwd)/docs/${PKG}/${PKG}.tag" >> docs/tags.yaml
done

[mikepurvis]

For interested parties, there's a beginning implementation of this here, built as a catkin_tools plugin: https://github.com/mikepurvis/catkin_tools_document

It's dependent on the change in #391, and still pretty rough around the edges, but will get a more formal release/announcement when those issues are resolved. I ended up not bothering with rosdoc_lite at all; it was easier to just pull in the pieces I needed rather than try to create a dependency. The basic idea is:

rosinstall_generator ros_base --tar --deps --flat > ros_base.rosinstall
rosinstall src ros_base.rosinstall -j8
catkin build
source devel/setup.bash
catkin document
# docs are now organized by package in a "docs space"

[mikepurvis]

Going to close this as done. There are now examples and packages on PyPI and launchpad. I don't think there's any reason to want this as part of catkin_tools proper— it's perfectly logical as an external plugin.