[ros-users] New Documentation Generation and Indexing for ros.org
Eitan Marder-Eppstein
eitan at hidof.com
Wed Oct 31 21:34:33 UTC 2012
Christian,
On Wed, Oct 31, 2012 at 5:57 AM, Christian Dornhege <
dornhege at informatik.uni-freiburg.de> wrote:
> Hi,
>
>
> A few things:
>> * Glad to hear that your stack headers are there for fuerte now. For
>> electric, I'm not sure what's going on since that's still handled by the
>> old documentation indexer. If I had to guess, I'd say that the packages
>> in question might not be included in the documentation index used for
>> electric. You can take a look at the list used here:
>> https://code.ros.org/svn/ros/**stacks/rosorg/trunk/rosdoc_**
>> rosorg/index/distro-electric.**yaml<https://code.ros.org/svn/ros/stacks/rosorg/trunk/rosdoc_rosorg/index/distro-electric.yaml>
>> .
>> I think that's what the electric job runs off. If you need a repo to be
>> indexed there, let me know and I can try to add it and see what happens.
>>
> Was this behavior maybe changed at some time? I remember it indexing our
> trunk/ URL. Now it seems that only the packages are indexed that have been
> released as debs.
>
The behavior for electric documentation always worked this way. However,
there was a separate indexer that ran off of rosinstall files documenting
whatever was in them, but that is no longer run in favor of the new system.
It's possible that this old indexer produced your headers and
documentation, but the docs for electric specifically were never generated.
With the old wiki, no one would have noticed this as per-distro browsing
wasn't something that was really possible to do. The old indexer job was
kind of weird to begin with since it could allow for documentation to be
mixed between distros... leading to some weird effects.
>
> See for example:
> http://www.ros.org/wiki/**freiburg_tools<http://www.ros.org/wiki/freiburg_tools>
> fuerte and electric package list are very different.
>
This is expected given that the electric indexer documents off of released
electric code.
>
> If there is no electric release, there is no index:
> http://www.ros.org/wiki/**rxparamedit?distro=electric<http://www.ros.org/wiki/rxparamedit?distro=electric>
This is also expected. To have this package documented, it would need to be
added to the distro file.
>
>
> Packages released for electric link to the release tag, fuerte to the
> trunk/ (or probably what we put in the distro file via github).
> http://www.ros.org/wiki/**octomap_server<http://www.ros.org/wiki/octomap_server>
>
> The yaml file you linked contains trunk/ and not the release tags, so I
> have to admit I'm not really sure where the electric index is built off.
It would seem you're right here. After poking around a bit, it seems that
the documentation for electric is built off of the electric.rosdistro file
directly, though the code is a bit weird in how it's doing this so I'm
still not completely positive. So that's:
https://code.ros.org/svn/release/trunk/distros/electric.rosdistro. This
sort of sucks since it means that to index anything in electric for
documentation, you have to release it.
>
>
> * The removal of the "repo" link is intentional. We made the decision to
>> remove automatic grouping of packages from the same "repo" as now most
>> people are using DVCS which means that we end up with lots of repos per
>> organization. So, we're going to start recommending that people
>> manually curate their organizations page to summarize and highlight
>> their organizations contributions, and then link to those pages as they
>> would to any other wiki reference.
>>
>> * The source link should still be there. With what package were you
>> finding it to be lacking?
>>
>
> OK, now source links have reappeared, maybe it just needed some time.
> But they only contain the link that is indexed, not the link to the
> individual package, e.g. for
> http://www.ros.org/wiki/**rxparamedit?distro=fuerte<http://www.ros.org/wiki/rxparamedit?distro=fuerte>
> Is this intended?
> I assume, this could be improved by making individual entries for
> stacks, which we'll have to make for groovy anyways, but still would
> only link to the stack source, not the package source.
>
I see. Without adding individual entries for stacks in the rosinstall file,
there's just no way for the documentation system to know what path to link
to. As far as it's concerned, all the code lives in that repo, it doesn't
try to be clever about inserting relative paths. I'll also note that this
is only an issue for SVN where checking out part of a repo is something
that might make sense to do. If you want these links to be for each stack,
you'll have to list them explicitly in the rosinstall files used for
documentation. This would work for both fuerte and groovy.
>
> Thank you for looking into this,
>
No problem. It's been super helpful to get some eyes on things to make sure
that the new system works well for everyone. All major changes come with
some amount of pain, thanks for your patience with everything.
Hope all is well,
Eitan
>
> Christian
>
>
> Thanks for the feedback and hope all is well,
>>
>> Eitan
>>
>> On Mon, Oct 29, 2012 at 9:21 AM, Christian Dornhege
>> <dornhege at informatik.uni-**freiburg.de<dornhege at informatik.uni-freiburg.de>
>> <mailto:dornhege at informatik.**uni-freiburg.de<dornhege at informatik.uni-freiburg.de>>>
>> wrote:
>>
>> Hi,
>> On 26.10.2012 20:06, Eitan Marder-Eppstein wrote:
>>
>> Hey all,
>>
>>
>> Thank you! I've just checked our wiki pages and package and stack
>> header are there again for fuerte, but not electric.
>>
>> One other thing: The package headers seem to only contain
>>
>> Repository/Source links for released packages and in that case to the
>> release tag. Is this a bug or a new feature?
>> If this is intended, would it be possible to create a Wiki Macro
>> that allows to add source information to the page?
>>
>> Best regards,
>> Christian
>>
>> 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/<http://ros.org/doc/api/nao___driver/>
>> <http://ros.org/doc/api/nao_**driver/<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/fuerte/__api/nao_driver/>
>> <http://ros.org/doc/fuerte/**api/nao_driver/<http://ros.org/doc/fuerte/api/nao_driver/>
>> >,
>> http://ros.org/doc/electric/__**api/nao_driver/<http://ros.org/doc/electric/__api/nao_driver/>
>> <http://ros.org/doc/electric/**api/nao_driver/<http://ros.org/doc/electric/api/nao_driver/>
>> >,
>> http://ros.org/doc/__**diamondback/api/nao_driver/<http://ros.org/doc/__diamondback/api/nao_driver/>
>> <http://ros.org/doc/**diamondback/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/<http://ros.org/rosdoclite/__fuerte/api/nao_driver/>
>> <http://ros.org/rosdoclite/**fuerte/api/nao_driver/<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<http://www.ros.org/wiki/alufr-__ros-pkg_trunk/Releases>
>> <http://www.ros.org/wiki/**alufr-ros-pkg_trunk/Releases<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/__octomap_ros/Releases>
>> <http://www.ros.org/wiki/**octomap_ros/Releases<http://www.ros.org/wiki/octomap_ros/Releases>
>> >
>> <http://www.ros.org/wiki/__**alufr-ros-pkg_trunk/Releases<http://www.ros.org/wiki/__alufr-ros-pkg_trunk/Releases>
>>
>> <http://www.ros.org/wiki/**alufr-ros-pkg_trunk/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.__googlec**ode.com/svn/trunk/__octomap_**
>> stacks/octomap_ros<http://googlecode.com/svn/trunk/__octomap_stacks/octomap_ros>
>>
>> <http://alufr-ros-pkg.**googlecode.com/svn/trunk/**
>> octomap_stacks/octomap_ros<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<dornhege at informatik.uni-__freiburg.de>
>> <mailto:dornhege at informatik.**uni-freiburg.de<dornhege at informatik.uni-freiburg.de>
>> >
>> <mailto:dornhege at informatik.__**uni-freiburg.de<http://uni-freiburg.de>
>>
>> <mailto:dornhege at informatik.**uni-freiburg.de<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>
>>
>>
>>
>> <http://www.ros.org/wiki/Get%_**_20Involved#Fuerte_and_later
>> <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.__googlec**__ode.com/svn/trunk/<http://googlec__ode.com/svn/trunk/>
>> <http://googlecode.com/svn/**trunk/<http://googlecode.com/svn/trunk/>
>> >
>>
>>
>> <http://alufr-ros-pkg.__google**code.com/svn/trunk/<http://googlecode.com/svn/trunk/>
>> <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>
>> <http://www.ros.org/wiki/nao__**_driver<http://www.ros.org/wiki/nao___driver>
>> >
>>
>>
>> <http://www.ros.org/wiki/nao__**_driver<http://www.ros.org/wiki/nao___driver>
>> <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>
>> <http://ros.org/wiki/humanoid_**__localization<http://ros.org/wiki/humanoid___localization>
>> >
>>
>>
>> <http://ros.org/wiki/humanoid_**__localization<http://ros.org/wiki/humanoid___localization>
>> <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>
>> <http://www.ros.org/wiki/__**footstep_planner<http://www.ros.org/wiki/__footstep_planner>
>> >
>>
>>
>> <http://www.ros.org/wiki/__**footstep_planner<http://www.ros.org/wiki/__footstep_planner>
>> <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>
>> <http://www.ros.org/wiki/__**octomap_ros<http://www.ros.org/wiki/__octomap_ros>
>> >
>>
>>
>> <http://www.ros.org/wiki/__**octomap_ros<http://www.ros.org/wiki/__octomap_ros>
>> <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>
>> <http://www.ros.org/browse/__**details.php?name=rxparamedit<http://www.ros.org/browse/__details.php?name=rxparamedit>
>> >
>> <http://www.ros.org/browse/__**details.php?name=rxparamedit<http://www.ros.org/browse/__details.php?name=rxparamedit>
>> <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>
>> <http://ros.org/wiki/__**rxparamedit<http://ros.org/wiki/__rxparamedit>
>> >
>>
>>
>> <http://ros.org/wiki/__**rxparamedit<http://ros.org/wiki/__rxparamedit>
>> <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>
>> <http://www.ros.org/wiki/__**octomap_ros/Releases<http://www.ros.org/wiki/__octomap_ros/Releases>
>> >
>>
>> <http://www.ros.org/wiki/__**octomap_ros/Releases<http://www.ros.org/wiki/__octomap_ros/Releases>
>> <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>
>> <http://www.ros.org/wiki/__**octomap_msgs/Releases<http://www.ros.org/wiki/__octomap_msgs/Releases>
>> >
>>
>>
>> <http://www.ros.org/wiki/__**octomap_msgs/Releases<http://www.ros.org/wiki/__octomap_msgs/Releases>
>> <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://uni-freiburg.de/~**hornunga<http://uni-freiburg.de/~hornunga>
>> >
>> <http://www.informatik.uni-__**freiburg.de/~hornunga<http://www.informatik.uni-__freiburg.de/~hornunga>
>> <http://www.informatik.uni-**freiburg.de/~hornunga<http://www.informatik.uni-freiburg.de/~hornunga>
>> >>
>>
>>
>>
>> ______________________________**_____________________
>>
>> ros-users mailing list
>> ros-users at code.ros.org <mailto:ros-users at code.ros.org**>
>> <mailto:ros-users at code.ros.org <mailto:ros-users at code.ros.org**
>> >__>
>> https://code.ros.org/mailman/_**___listinfo/ros-users<https://code.ros.org/mailman/____listinfo/ros-users>
>> <https://code.ros.org/mailman/**__listinfo/ros-users<https://code.ros.org/mailman/__listinfo/ros-users>
>> >
>>
>> <https://code.ros.org/mailman/**__listinfo/ros-users<https://code.ros.org/mailman/__listinfo/ros-users>
>> <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 <tel:%2B49%20761%20203%208225>
>> <tel:%2B49%20761%20203%208225>
>>
>> ______________________________**_____________________
>>
>> ros-users mailing list
>> ros-users at code.ros.org <mailto:ros-users at code.ros.org**>
>> <mailto:ros-users at code.ros.org <mailto:ros-users at code.ros.org**
>> >__>
>> https://code.ros.org/mailman/_**___listinfo/ros-users<https://code.ros.org/mailman/____listinfo/ros-users>
>> <https://code.ros.org/mailman/**__listinfo/ros-users<https://code.ros.org/mailman/__listinfo/ros-users>
>> >
>>
>> <https://code.ros.org/mailman/**__listinfo/ros-users<https://code.ros.org/mailman/__listinfo/ros-users>
>> <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
>>
>>
>>
>> ______________________________**___________________
>> ros-users mailing list
>> ros-users at code.ros.org <mailto:ros-users at code.ros.org**>
>> https://code.ros.org/mailman/_**_listinfo/ros-users<https://code.ros.org/mailman/__listinfo/ros-users>
>> <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 <tel:%2B49%20761%20203%208225>
>> ______________________________**___________________
>> ros-users mailing list
>> ros-users at code.ros.org <mailto:ros-users at code.ros.org**>
>> https://code.ros.org/mailman/_**_listinfo/ros-users<https://code.ros.org/mailman/__listinfo/ros-users>
>> <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
>>
>>
>>
>> ______________________________**_________________
>> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-users/attachments/20121031/e1e8e75b/attachment-0004.html>
More information about the ros-users
mailing list