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