[ros-users] ROS versioning & wiki structure

Georg Heppner heppner at fzi.de
Mon Nov 24 21:46:38 UTC 2014


The main reason for me not writing beautiful doxygen documentation is 
that it is actually more work to get it to look readable than a wiki.
> 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?
This is indeed confusing. I figured the correct/best practice way was to 
describe the interface directly at the wiki level. Its the most visible 
and easiest to navigate. Completely auto generating interface 
Information is quite hard if you don’t want to reverse engineer every 
code automatically. So the developer has to describe it somewhere. 
Rather than putting more into the doxygen I would be in favour of having 
a best practice for what should be presented at the wiki page for a bare 
minimum. (I think the wiki tutorials state somewhere that you should at 
least provide interface descriptions).
> 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.
But wouldn’t it be much nicer to use the nicely formated macros for 
this? I think it`s a huge benefit that most of the wiki pages look the 
same in regard to this interface definition. By pulling this information 
out of the page you would loose this nice uniformity. You could of 
course parse the doxygen, but if there is already a nice macro to fill 
out, why not use that?

The doxygen documentation is quite visible for anyone searching for it. 
The user that just wants to work with the node does not need that 
information most of the time as it contains much more than he would want 
to know. The right place for interface documentation should be at the 
wiki page level. Anything going beyond that is probably fine within the 
API description.

Regarding auto generated content: I think the current wiki structure is 
quite good as it is. A lot of the information is auto generated from the 
doc jobs giving you the instant achievement if everything is green at 
the top of your wiki page, links to the repo, stati of jenkins builds 
and so on. The Doxygen is auto generated and quite visible at the top of 
your documentation. Also I think the wiki adds valuable information that 
could not be adequately be captured within a file contained just in the 
source code. Of course you could do a very nice doxygen documentation 
but that is much harder than writing a nice wiki page including some 
pictures or even a youtube link of the package in action.

Also In my opinion the current way of having macros for different 
versions of a release is the best way to handle that. As Dirk pointed 
out, the API is auto generated for every release so the most up to date 
information can be found there. Even if the interfaces change during 
releases they will most likely not change completely. Also the rest of 
the documentation (concepts, failure handling, requirements etc.) will 
probably stay mostly the same. So I am in favour of small change macros 
instead of big copies with small changes.

Best Regards
Georg

>
> On 24 November 2014 at 12:39, Dirk Thomas <dthomas at osrfoundation.org 
> <mailto: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 <mailto: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 <mailto:miquel.massot at gmail.com>
>         <https://github.com/miquelmassot>
>
>
>         2014-11-24 17:39 GMT+01:00 Mike Purvis
>         <mpurvis at clearpathrobotics.com
>         <mailto: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 <mailto: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
>                 <mailto:miquel.massot at gmail.com>
>                 <https://github.com/miquelmassot>
>
>
>                 2014-11-24 16:42 GMT+01:00 Mike Purvis
>                 <mpurvis at clearpathrobotics.com
>                 <mailto: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
>                     <mailto:jonathan.bohren at gmail.com>> wrote:
>
>                         On Mon Nov 24 2014 at 3:38:46 AM Miquel Massot
>                         Campos <miquel.massot at gmail.com
>                         <mailto: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
>                         <mailto:ros-users at lists.ros.org>
>                         http://lists.ros.org/mailman/listinfo/ros-users
>
>
>
>                     _______________________________________________
>                     ros-users mailing list
>                     ros-users at lists.ros.org
>                     <mailto:ros-users at lists.ros.org>
>                     http://lists.ros.org/mailman/listinfo/ros-users
>
>
>
>                 _______________________________________________
>                 ros-users mailing list
>                 ros-users at lists.ros.org <mailto:ros-users at lists.ros.org>
>                 http://lists.ros.org/mailman/listinfo/ros-users
>
>
>
>             _______________________________________________
>             ros-users mailing list
>             ros-users at lists.ros.org <mailto:ros-users at lists.ros.org>
>             http://lists.ros.org/mailman/listinfo/ros-users
>
>
>
>         _______________________________________________
>         ros-users mailing list
>         ros-users at lists.ros.org <mailto:ros-users at lists.ros.org>
>         http://lists.ros.org/mailman/listinfo/ros-users
>
>
>
>     _______________________________________________
>     ros-users mailing list
>     ros-users at lists.ros.org <mailto: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


-- 
.........................................................
M.Sc. Georg Heppner
Wissenschaftlicher Mitarbeiter Interaktive Diagnose- und Servicesysteme (IDS)

FZI Forschungszentrum Informatik
Haid-und-Neu-Str. 10–14
76131 Karlsruhe, Germany
Tel.: +49 721 9654-248
Fax: +49 721 9654-249

heppner at fzi.de
www.fzi.de

.........................................................
FZI Forschungszentrum Informatik am Karlsruher Institut für Technologie
Stiftung des bürgerlichen Rechts
Stiftung Az: 14-0563.1 Regierungspräsidium Karlsruhe
Vorstand: Prof. Dr. Andreas Oberweis, Prof. Dr. Ralf Reussner,
Jan Wiesenberger, Prof. Dr.-Ing. J. Marius Zöllner
Vorsitzender des Kuratoriums: Ministerialdirigent Günther Leßnerkraus
.........................................................

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-users/attachments/20141124/f71f872b/attachment.html>


More information about the ros-users mailing list