[ros-users] New Documentation Generation and Indexing for ros.org

Wed Oct 24 22:52:18 UTC 2012

Hey David,

So, the current structure of things makes it pretty hard to write
instructions that could allow someone to run their own ROS wiki/docs site.
Code to make the wiki, docs, etc. turn over is spread among a number of
different repositories, with even more repositories needed to hold
meta-information (like the location of Doxygen tag files for
cross-referencing purposes). Right now, we also assume that MoinMoin is
configured a certain way (with a bunch of custom macros installed), we
assume that a Jenkins build farm is set up to run jobs, and we assume
certain repositories are used to store index information on what rosinstall
files should be documented.

With that said, most of these assumptions are things that can be
parameterized, scripts running inside a Jenkins chroot can be tweaked to
allow for running on the command line, and instructions can be written on
how to configure MoinMoin and the docs server correctly. So, in the long
term, it's definitely possible to streamline the process, and allow for
wiki/docs sites to be hosted by many different parties. There's just a lot
of work involved in making that possibility a reality.

With rosdoc_lite <http://www.ros.org/wiki/rosdoc_lite>, we've taken a small
step in the right direction since it allows users to document individual
packages relatively easily. However, all the custom code to pass the right
cross-referencing information to rosdoc_lite, update indexing systems, run
many doc jobs in parallel, display the correct information on the wiki, and
upload documentation to the correct location still makes cloning the wiki
pipeline a mess. In particular, the need to support fuerte catkin, groovy
catkin, and non-catkin packages (yes, they all have slightly different
package or manifest xml files and CMake invocations) leads to some scripts
that aren't as clean as you'd like. Once hydro comes around, and the build
system finally settles, the task creating nice standalone tools will also
get easier.

Hopefully, this is at least a reasonable explanation as to why the
instructions you seek don't exist. If you were to get super ambitious,
wanting to pull code apart and make it more generic, the following
repositories would be of use:

roswiki (wiki macros we use for MoinMoin): http://ros.org/wiki/roswiki
jenkins_scripts (holds doc scripts that make all the cross-referencing
goodness possible): http://ros.org/wiki/jenkins_scripts
jenkins_tools (tools that allow you to run the doc script in a local chroot
or on a jenkins instance): http://ros.org/wiki/jenkins_tools

Hope all is well,

Eitan

On Wed, Oct 24, 2012 at 2:22 PM, David Lu!! <davidvlu at gmail.com> wrote:

> If someone wanted to set up their own wiki/docs site for experimenting
> with a fork of the current repo (and this person wasn't entirely too
> busy trying to graduate), are there any instructions on how to do
> that?
>
> After the conversations at ROSCon and on this list, I think there's
> potential for further documentation of code quality and maintenance.
>
> -DL!!
>
> On Mon, Oct 22, 2012 at 8:00 PM, Eitan Marder-Eppstein <eitan at hidof.com>
> wrote:
> > Hey all,
> >
> > So, as part of the infrastructure changes that we're making for ROS
> Groovy,
> > we've revamped the way documentation generation and indexing works. The
> new
> > system handles cross-referencing of Doxygen properly, is capable of
> > documenting catkin packages, and can run documentation generation with
> > independent jobs for each repository indexed. To support this new system,
> > there is a new documentation generation tool for ROS called rosdoc_lite,
> > which is a stripped down version of rosdoc that adds support for Doxygen
> > cross-references and catkin. For more information on using rosdoc_lite
> as a
> > standalone tool, please see http://ros.org/wiki/rosdoc_lite.
> >
> > Since catkin packages were never properly documented and indexed in
> Fuerte,
> > we've also decided to roll out this new documentation indexer for Fuerte
> in
> > addition to Groovy. This means that, if you have Fuerte or Groovy
> packages
> > that you'd like to have indexed and documented on ros.org, you'll need
> to
> > register them with the new indexing system. For detailed instructions on
> how
> > to add your packages to the index, please see this page, but it should
> be as
> > simple as creating a rosinstall file for your stack, metapackage, or
> > repository group.
> >
> > The new documentation also comes with updated wiki macros for generating
> > package and stack headers on ros.org. These headers have tabs for
> > diamondback, electric, fuerte, and groovy that you can easily switch
> > between. They also allow you to include distro specific information with
> > each package (much like with the version macro). For more information on
> > these new headers, and how they work, please see:
> > http://www.ros.org/wiki/WikiMacros. Since they are backwards compatible,
> > we've already switched the wiki over.
> >
> > On a logistical note, we're already using the new indexer to build
> > documentation for Groovy packages, but have not switched the wiki over to
> > use the new indexer for Fuerte quite yet. First, we want to make sure
> that
> > the community has a chance to add their packages to the indexer. So,
> within
> > the next two weeks, please take some time to add any package you
> maintain to
> > the indexer. Once again, to do this, please follow the instructions here.
> >
> > Some useful pages:
> >
> > Tickets for rosdoc_lite
> > (https://github.com/ros-infrastructure/rosdoc_lite/issues)
> > Tickets for indexing system
> > (https://github.com/ros-infrastructure/jenkins_scripts/issues)
> >
> > Hope all is well,
> >
> > Eitan
> >
> > --
> > Eitan Marder-Eppstein
> > President, hiDOF Inc.
> > http://www.hidof.com
> >
> >
> > _______________________________________________
> > ros-users mailing list
> > ros-users at code.ros.org
> > https://code.ros.org/mailman/listinfo/ros-users
> >
> _______________________________________________
> ros-users mailing list
> ros-users at code.ros.org
> https://code.ros.org/mailman/listinfo/ros-users
>

-- 
Eitan Marder-Eppstein
President, hiDOF Inc.
http://www.hidof.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-users/attachments/20121024/739601d0/attachment-0004.html>