[ros-users] ROS versioning & wiki structure

Mon Nov 24 18:04:41 UTC 2014

The only package I'm aware of like this is joy:

http://wiki.ros.org/joy
http://docs.ros.org/api/joy/html/

Unlike most other packages, the node and parameter docs are on the doxygen
page rather than the wiki page— I find this actually more confusing than
helpful. Is there another better example of this idea?

Alternatively, if we like the joy package as an example, how can we elevate
the visibility of the doxygen page content on the ROS wiki page? For
example, by a macro which could suck it in and display it there.

On 24 November 2014 at 12:39, Dirk Thomas <dthomas at osrfoundation.org> wrote:

> We don't have to "develop" .roswiki files - we already have a very similar
> feature: the doc jobs.
>
> A doc job is ROS distro release specific (if the source repository has
> different branches) and all the resources are managed within the source
> repo.
> It is not only about API documentation - you can put arbitrary content in
> it which some packages already do make use of.
>
> - Dirk
>
> On Mon, Nov 24, 2014 at 8:52 AM, Miquel Massot Campos <
> miquel.massot at gmail.com> wrote:
>
>> The dependencies are one of the main reasons. For example, imagine that
>> you are going to download and build a package on a robot where there is not
>> ROS visualization-related packages. Then you must go to the package, remove
>> the dependency and the tutorials. I think that's not a good idea unless
>> rviz is only the launchfiles.
>>
>> Besides, how many packages will require an extra tutorial package? Not
>> that many I think. Normaly, with a good list of tutorials inside the parent
>> package should be enough. For special packages where visualization or
>> implementation is important, then yes.
>>
>> Miquel Massot
>>
>> miquel.massot at gmail.com    <https://github.com/miquelmassot>
>>
>>
>> 2014-11-24 17:39 GMT+01:00 Mike Purvis <mpurvis at clearpathrobotics.com>:
>>
>>> Some of what you want already exists:
>>>
>>> https://github.com/ros/ros_tutorials
>>> https://github.com/ros/geometry_tutorials
>>>
>>> The corresponding wiki tutorial pages are spotty, though— sometimes they
>>> suck in sources directly from raw.github links, other times it's pasted in.
>>> It also doesn't seem clear whether the tutorial wants you to recreate the
>>> package from scratch, check it out as source and fiddle with it.
>>>
>>> I'm not certain that every package should have a companion X_tutorials
>>> package, though. What about packaging the tutorials right within the
>>> package? The only risk there is of tutorial binaries or launchers needing
>>> additional dependencies (say, rviz).
>>>
>>>
>>> On 24 November 2014 at 11:29, Miquel Massot Campos <
>>> miquel.massot at gmail.com> wrote:
>>>
>>>> +1 to mix and match wiki-editable with source-controlled wiki content.
>>>>
>>>> For the tutorials I'd like to discuss a solution that has come to my
>>>> mind. Let's keep it simple with the tools available. Why don't we just make
>>>> tutorial packages with example source code? Therefore, the documentation
>>>> could parse if that package ends in "*tutorials*" it must be added to
>>>> the documentation of the parent package. Furthermore, the build
>>>> dependencies will be kept and the sources can be built in the current
>>>> buildfarm (debian package generation is not necessary). There are some
>>>> packages that are structured like this: ros_tutorials,
>>>> navigation_tutorials, geometry_tutorials...
>>>>
>>>> However, what if a developer wants to write tutorials without fully
>>>> compilable code? I think that the tutorials can be placed in the .
>>>> *roswiki* file along with the package documentation as well as in
>>>> compilable *pkg_tutorials*. Another mix&match.
>>>>
>>>>
>>>>
>>>> Miquel Massot
>>>>
>>>> miquel.massot at gmail.com    <https://github.com/miquelmassot>
>>>>
>>>>
>>>> 2014-11-24 16:42 GMT+01:00 Mike Purvis <mpurvis at clearpathrobotics.com>:
>>>>
>>>>> The ideal IMO would be to implement this as a macro— so much as the
>>>>> wiki today displays the manifest.yml information generated from doc jobs,
>>>>> the wiki of tomorrow could have a macro which sucks in a
>>>>> similarly-extracted file.
>>>>>
>>>>> This allows the flexibility to mix and match wiki-editable content
>>>>> where that is appropriate with blobs of source-controlled content, where
>>>>> *that* is more appropriate. It also offers a sane migration strategy.
>>>>>
>>>>> The really, really ideal would be if the "mytutorial1.roswiki" file in
>>>>> my repo could actually optionally be itself a templated affair, perhaps
>>>>> supporting a format like mytutorial1.rowiki.em, so that things like blobs
>>>>> of example source code or whatever could be sucked in from marked-off
>>>>> sections of actual working examples which can then be tested during the
>>>>> source build.
>>>>>
>>>>> On 24 November 2014 at 10:18, Jonathan Bohren <
>>>>> jonathan.bohren at gmail.com> wrote:
>>>>>
>>>>>> On Mon Nov 24 2014 at 3:38:46 AM Miquel Massot Campos <
>>>>>> miquel.massot at gmail.com> wrote:
>>>>>>
>>>>>>> In my opinion, maintaining a repo and the documentation in two
>>>>>>> different sites is a bit confusing. One often makes changes to the
>>>>>>> repository without remembering how the roswiki entry was done, thus
>>>>>>> breaking the completeness or correctness of it. As most of us are
>>>>>>> developing on GitHub, would it make sense to have a document in each of our
>>>>>>> repositories "*something.roswiki"* so that the documentation
>>>>>>> generator
>>>>>>>
>>>>>> pastes it into the roswiki?
>>>>>>>
>>>>>>
>>>>>> I agree. The wiki is broken, and package documentation should reside
>>>>>> in the packages wherever the code is hosted.
>>>>>>
>>>>>> Unfortunately, as Dirk said, "whatever change you propose must be
>>>>>> implemented by someone."  So, I'm asking directly:
>>>>>>
>>>>>> What resources does OSRF have to re-work the ROS wiki pages for
>>>>>> packages and tutorials in a way that simply aggregates documentation from
>>>>>> package source repositories?
>>>>>>
>>>>>> -j
>>>>>>
>>>>>> _______________________________________________
>>>>>> ros-users mailing list
>>>>>> ros-users at lists.ros.org
>>>>>> http://lists.ros.org/mailman/listinfo/ros-users
>>>>>>
>>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> ros-users mailing list
>>>>> ros-users at lists.ros.org
>>>>> http://lists.ros.org/mailman/listinfo/ros-users
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> ros-users mailing list
>>>> ros-users at lists.ros.org
>>>> http://lists.ros.org/mailman/listinfo/ros-users
>>>>
>>>>
>>>
>>> _______________________________________________
>>> ros-users mailing list
>>> ros-users at lists.ros.org
>>> http://lists.ros.org/mailman/listinfo/ros-users
>>>
>>>
>>
>> _______________________________________________
>> ros-users mailing list
>> ros-users at lists.ros.org
>> http://lists.ros.org/mailman/listinfo/ros-users
>>
>>
>
> _______________________________________________
> ros-users mailing list
> ros-users at lists.ros.org
> http://lists.ros.org/mailman/listinfo/ros-users
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-users/attachments/20141124/f9637eef/attachment.html>