Enable XML output for sphinx breathe plugin

[paulbovbel]

The breathe plugin (https://breathe.readthedocs.org/) allows embedding doxygen's output inside sphinx, but requires that the GENERATE_XML option is turned on in the config.

[paulbovbel]

Addresses half of #54

[jack-oquin]

What else is needed to resolve #54?

[paulbovbel]

To distribute python-breathe via debs, however this is outside the scope any changes to this repo.

python-breathe could be backported into trusty from utopic (https://launchpad.net/ubuntu/utopic/+source/breathe). We do this internally, but I'm not sure what would be the best way to do this for public. Maybe via https://github.com/ros-infrastructure/reprepro-updater?

[paulbovbel]

I take it back - we would need to add python-breathe as a run dependency to this package.

@tfoote, would you have any comment on the feasibility of adding a python-breathe backport to trusty, and adding it as a dependency for rosdoc_lite?

[tfoote]

It would be possible, but it would be a pretty big pain as we'd need to build saucy debs still.

I'd suggest targeting kinetic for this change and then the backport won't be necessary.

[paulbovbel]

Sounds good to me. @jack-oquin, if you want to target this for kinectic-devel, this PR is ready. My only request would be that you still create a release tag (even though kinetic is not released yet) so that we can build rosdoc_lite with breathe for indigo in our environment.

[jack-oquin]

I agree that kinetic is a reasonable release target and that we should avoid changing dependencies for the earlier releases.

[paulbovbel]

+1, please let me know if there's anything outstanding to be done

[jack-oquin]

@tfoote: there have been substantial changes to the build farm since I last looked, but it used to check out the master sources from this repository for building doc jobs.

• Is that still true?
• Will the new dependency cause trouble for Indigo and Jade doc jobs?

[tfoote]

@jack-oquin It looks like we still pull the default branch: https://github.com/ros-infrastructure/ros_buildfarm/blob/master/ros_buildfarm/templates/doc/doc_job.xml.em#L86

I think it would also need to be inserted here: https://github.com/ros-infrastructure/ros_buildfarm/blob/master/scripts/doc/create_doc_task_generator.py#L473

The one problem I see is that it's only available on vivid and newer, where we run our builds on the LTS releases. aka trusty and soon to be xenial

[jack-oquin]

That's what I was afraid of. If we merge this into master it's likely to break doc builds on Trusty. Both Trusty and Indigo are LTS.

I have never been happy about the build farm checking out an unreleased source version from master. Surely there is a better approach. Should it use a branch named for the release being documented?

I am open to other ideas. Can the build farm actually install the current released version for each distro? That seems best. But, what about new releases, like Kinetic? No Kinetic version exists yet. Should we use master in that case, only?

[jack-oquin]

Any suggestions how I can merge this without breaking doc builds on Trusty?

[bit-pirate]

@paulbovbel has this PR been replaced by another?

[paulbovbel]

Nope, just cleaning out my dash of dead PRs. Doesn't seem like this change is feasible given the buildfarm architecture.

[mikepurvis]

Note also that we (Clearpath) are building our docs a different way now, so it's a lot less relevant to us:

https://github.com/mikepurvis/catkin_tools_document