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

Fri Oct 26 18:15:13 UTC 2012

One more thing, my comment about the releases page applies to all Groovy
catkin packages, but for the old stacks I can write some code to do the
right (old) thing, just assuming the stack is a release unit. So, with a
little extra code, you won't have to change your rosinstall file. I'll work
on building in support for that now.

On Fri, Oct 26, 2012 at 11:06 AM, Eitan Marder-Eppstein <eitan at hidof.com>wrote:

> Hey all,
>
> A few things:
>
> * The old wiki macros only ever displayed headers from the latest
> successful run of the indexer. They never displayed headers from different
> distros. So, there was actually no way to tell previously if documentation
> was broken for electric or diamondback without clicking on something like
> the "Code API" link or going to the documentation directly.
>
> * Take the nao_driver package for example. The following page exists (
> http://ros.org/doc/api/nao_driver/), but the three distro specific pages
> do not (http://ros.org/doc/fuerte/api/nao_driver/,
> http://ros.org/doc/electric/api/nao_driver/,
> http://ros.org/doc/diamondback/api/nao_driver/). This means that, at one
> point, documentation for the nao_driver package succeeded, but we don't
> even know in which distro that was. All we know is that it fails now, for
> reasons that may not be at all related to that stack, on all three distros.
> The good news is that it works with the new indexer:
> http://ros.org/rosdoclite/fuerte/api/nao_driver/. So, when we switch over
> Fuerte to the new doc system, things will display correctly. I'm leaning
> towards doing this later today.
>
> * The reason that roscpp lacks header information for Fuerte is actually
> different. The ros_comm stack was ported over to catkin for Fuerte, but the
> old documentation pipeline was never updated to support catkin-ized
> packages. As such, roscpp was never properly documented for Fuerte.
> However, no one noticed because the last successful run of the roscpp
> header (which might have been in electric) was displayed and used on the
> wiki.
>
> * The information used to generate the browse pages is actually different
> (in the old system) from the information used to generate the package
> headers. So, the rosbrowse page isn't the most reliable way to see if
> something is known by the indexer or properly documented. This will all
> change with the new system though I still have to do some wiki macros work
> to get browsing up with the new stuff.
>
> * After writing this e-mail, I've decided to switch over the wiki for
> Fuerte. I'll send out a separate announcement soon, but all of your pages
> should work now. One thing to note is that, with Groovy switching over to
> meta-packages, release pages will be based off of repositories rather than
> stacks. In most cases, this amounts to using the same name but, for certain
> SVN situations, like alufr-ros-pkg, you might want to change your
> rosinstall file to list each stack separately with a local-name
> corresponding to that of the stack. Otherwise, the indexer will assume that
> you mean to release all of alufr-ros-pkg as a unit (since you document it
> as a unit) and link to a page on the wiki called
> http://www.ros.org/wiki/alufr-ros-pkg_trunk/Releases rather than
> something like http://www.ros.org/wiki/octomap_ros/Releases<http://www.ros.org/wiki/alufr-ros-pkg_trunk/Releases>.
> Also, there is still some work that needs to be done for auxiliary pages
> like Releases, the Browse page, etc. to work correctly. So, just a heads up
> that things there may be a little flaky for a day or two. Just to make my
> local-name point clear, here's a rosinstall file for octomap_ros that would
> lead to proper release links:
>
> - svn:
>     local-name: octomap_ros
>     uri:
> http://alufr-ros-pkg.googlecode.com/svn/trunk/octomap_stacks/octomap_ros
>
> Hope all is well,
>
> Eitan
>
> On Fri, Oct 26, 2012 at 8:59 AM, Christian Dornhege <
> dornhege at informatik.uni-freiburg.de> wrote:
>
>> On 26.10.2012 17:40, Armin Hornung wrote:
>>
>>> On 2012-10-23 03:00, Eitan Marder-Eppstein wrote:
>>>
>>>>
>>>> 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
>>>> <http://www.ros.org/wiki/Get%**20Involved#Fuerte_and_later<http://www.ros.org/wiki/Get%20Involved#Fuerte_and_later>
>>>> >.
>>>>
>>>
>>> Is the old indexer information completely dismissed? It appears that the
>>> wiki information is now working only for packages & stacks that were
>>> released for diamondback or electric. We had our complete repository
>>> indexed at http://alufr-ros-pkg.**googlecode.com/svn/trunk/<http://alufr-ros-pkg.googlecode.com/svn/trunk/>and now only
>>> packages appear properly that were released in the past, e.g.:
>>>
>>> http://www.ros.org/wiki/nao_**driver<http://www.ros.org/wiki/nao_driver> - not working at all
>>> http://ros.org/wiki/humanoid_**localization<http://ros.org/wiki/humanoid_localization> - not working at all
>>> http://www.ros.org/wiki/**footstep_planner<http://www.ros.org/wiki/footstep_planner> - only information for
>>> electric works (was released once)
>>> http://www.ros.org/wiki/**octomap_ros<http://www.ros.org/wiki/octomap_ros> - only information for fuerte works
>>>
>>
>> The indexer seems to know this, but it's not arriving at the package
>> pages, see for example:
>> Package List: http://www.ros.org/browse/**details.php?name=rxparamedit<http://www.ros.org/browse/details.php?name=rxparamedit>
>> Wiki Page: http://ros.org/wiki/**rxparamedit<http://ros.org/wiki/rxparamedit>
>>
>> It seems to affect everything, as even roscpp
>> (http://ros.org/wiki/roscpp) does not have the header for fuerte.
>>
>> As I see it, the browse pages take the information from the current
>> state of the indexed repository, but the wiki page header are generated
>> from the releases (only). Is this maybe even intended behaviour?
>>
>> Cheers,
>>   Christian
>>
>>  We resubmitted the repo for indexing in fuerte with a pull request, so I
>>> guess that will at least clear up. But what about electric and earlier?
>>>
>>>
>>> As a side note http://www.ros.org/wiki/**octomap_ros/Releases<http://www.ros.org/wiki/octomap_ros/Releases>appears to
>>> be broken and http://www.ros.org/wiki/**octomap_msgs/Releases<http://www.ros.org/wiki/octomap_msgs/Releases>empty, any
>>> idea how to fix it?
>>>
>>> Cheers,
>>> Armin
>>>
>>> --
>>> Armin Hornung
>>> Humanoid Robots Lab, Albert-Ludwigs-Universität Freiburg
>>> Contact:http://www.informatik.**uni-freiburg.de/~hornunga<http://www.informatik.uni-freiburg.de/~hornunga>
>>>
>>>
>>>
>>> ______________________________**_________________
>>> ros-users mailing list
>>> ros-users at code.ros.org
>>> https://code.ros.org/mailman/**listinfo/ros-users<https://code.ros.org/mailman/listinfo/ros-users>
>>>
>>>
>>
>> --
>> Albert-Ludwigs-University
>> Institute of Computer Science
>> Research Group Foundations of Artificial Intelligence
>> Georges-Köhler-Allee 52
>> 79110 Freiburg
>> Phone: +49 761 203 8225
>>
>> ______________________________**_________________
>> ros-users mailing list
>> ros-users at code.ros.org
>> https://code.ros.org/mailman/**listinfo/ros-users<https://code.ros.org/mailman/listinfo/ros-users>
>>
>
>
>
> --
> Eitan Marder-Eppstein
> President, hiDOF Inc.
> http://www.hidof.com
>
>

-- 
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/20121026/18d599ca/attachment-0004.html>