[ros-users] ROS versioning & wiki structure

Miquel Massot Campos miquel.massot at gmail.com
Mon Nov 24 16:52:12 UTC 2014


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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-users/attachments/20141124/64f7ea28/attachment.html>


More information about the ros-users mailing list