documentation tool cleanups

[vrabaud]

Hi, we now have two tools for documentation:

• catkin_doxygen (in doc/tools)
• catkin_sphinx (in a different repo)

They should either be both in catkin, both independent or both in some catkin_doc/catkin_tools repo no ?
And maybe there should only be one doc target that merges both too ?

[sotte]

+1
This should be cleaned up.

[vrabaud]

BTW, catkin_sphinx has no CMake macro (like catkin_doxygen has), hence no target and the build has to be manual (which is not good when you are building intersphinx documentation). FYI, there used to be a catkin_sphinx macro. I still am using the original version which is still in ecto:
https://github.com/plasmodic/ecto/blob/master/cmake/doc.cmake

[jack-oquin]

+1 to adding a make doc target.

Each package can define a doc_{$PROJECT_NAME} target, with the top-level doc depending on them all.

[dirk-thomas]

Adding doc generation to each package would be great. But how does that relate to our existing infrastructure for buildings docs for the wiki? Won't it be difficult to generate docs with cross references etc.? Where should that new doc target be used?

[jack-oquin]

Good question, Dirk.

I suppose running rosdoc_lite could be the default target whenever $CATKIN_ENABLE_DOCS is set to a true value.

I do not think rosdoc_lite can or should be capable of handling every single project's documentation needs. It would quickly become rosdoc_heavy and probably still not satisfy some folks.

It would be great if this option could somehow affect the doc build farm jobs, but I don't see how to accomplish that either. Maybe understanding the internals better would suggest some way.

[vrabaud]

For cross-references (in Sphinx at least) I had a conf.py that had a condition whether I was in build space or in install space (cross references are either local or remote).

You also need to consider that you can have both doxygen and sphinx documentation (and one depending on the other (yeah, the ecto docs are pretty intense :) ).

And I would personnally see that target used by doclite and yes, I do not know much about it either :)

[dirk-thomas]

Without a detailed plan how things should work based on that, how they integrate into the current infrastructure / what needs to be changed I think we should not add any half-baked things for now.

I would like to see a global doc target but then this should also be utilized when generating the documentation for the wiki. And as far as I can see that goal would take quite some effort.

[jack-oquin]

How about some minor fixes to remove the more egregious inconsistencies, without attempting to change the build farm doc jobs?

I'd hate to see us doing nothing. The current lack of good ROS documentation is quite discouraging.

[dirk-thomas]

Fixes/improvements are always good. Please point out specific stuff and/or ticket it. At best someone will also look into those since we are very short on time and doc stuff is likely not at the top of the todo list.

[dirk-thomas]

I will close this issue since it is unlikely that there will be progress on this is in the future and it is unclear how this repo would be involved.