Ask Your Question
1

Custom Doxyfile options with rosdoc_lite

asked 2014-02-20 07:33:41 -0500

mkoval gravatar image

updated 2014-02-24 08:57:06 -0500

I would like to enable an input filter in my Doxyfile used when calling rosdoc_lite with the Doxygen backend. There are a few Doxygen customization options listed in the Doxygen builder section of the rosdoc_lite Wiki page, but there doesn't seem to be any way to append arbitrary options to the Doxyfile. Is there any way to get rosdoc_lite to use a custom Doxyfile template?

My immediate goal is to enable the Doxypy input filter for Python files. In the future, I also plan to change some of the formatting options.

Edit: We're building the documentation myself on an internal server, so it is not a hard requirement for our Doxyfile to work on the ROS build farm. One option is to to add a command-line option to rosdoc_lite that can point to a different Doxyfile (rather than the default templates/doxy.template). Alternatively, we can give up on using rosdoc_lite and just invoke Doxygen directly.

edit retag flag offensive close merge delete

1 Answer

Sort by ยป oldest newest most voted
0

answered 2014-02-22 03:49:45 -0500

joq gravatar image

updated 2014-02-22 03:50:15 -0500

The rosdoc_lite package aims to provide a simple, generic interface that can automatically generate documentation for the ROS wiki. As such, it does not support full customization, which would be hard for the build farm to handle, because it does not know what additional documentation packages might be needed.

There has been some discussion of adding a <doc_depend> tag to a future package.xml format, which might help with this eventually.

The usual recommendation for those with specialized documentation requirements is to use Doxygen directly and generate their documentation manually.

If you have specific options you would like to add for the Doxygen builder, you can submit a pull request. But, please avoid adding additional documentation package dependencies and breaking the build farm. I suppose we could add another package dependency to all the doc build jobs, but would need to anticipate reasonably widespread use to justify doing that.

I have never used doxypy. Most ROS Python packages use sphinx or epydoc, which are supported by rosdoc_lite. For most Python documentation tasks, my personal preference is sphinx.

edit flag offensive delete link more

Comments

Thanks for the reply. We have a lot of mixed C++ and Python code, so our preference is to use the same engine for both languages. Do you think Sphinx or Epydoc is a better fit for this? I also edited my question with a more detailed explanation with our setup.

mkoval gravatar image mkoval  ( 2014-02-24 08:55:18 -0500 )edit

I generally use both Sphinx and Doxygen in that situation, which requires a rosdoc.yaml like this: https://github.com/ros-geographic-info/geographic_info/blob/master/geodesy/rosdoc.yaml .

joq gravatar image joq  ( 2014-02-24 10:21:05 -0500 )edit

Since you are building the docs manually, if you prefer to use Doxygen for everything, there is no harm in invoking it directly. You don't need rosdoc_lite for that.

joq gravatar image joq  ( 2014-02-24 10:22:39 -0500 )edit

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Question Tools

1 follower

Stats

Asked: 2014-02-20 07:33:41 -0500

Seen: 322 times

Last updated: Feb 24 '14