<html>
<head>
<meta content="text/html; charset=windows-1252"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">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.<br>
</div>
<blockquote
cite="mid:CACsJT9PF4Fh0Yi+Y7RLADScUfAT-ND4aWYDqJ=U72tamBTZC8A@mail.gmail.com"
type="cite">
<meta http-equiv="Content-Type" content="text/html;
charset=windows-1252">
<div dir="ltr">The only package I'm aware of like this is joy:
<div><br>
</div>
<div><a moz-do-not-send="true" href="http://wiki.ros.org/joy">http://wiki.ros.org/joy</a><br>
</div>
<div><a moz-do-not-send="true"
href="http://docs.ros.org/api/joy/html/">http://docs.ros.org/api/joy/html/</a><br>
</div>
<div><br>
</div>
<div>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?</div>
</div>
</blockquote>
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).<br>
<blockquote
cite="mid:CACsJT9PF4Fh0Yi+Y7RLADScUfAT-ND4aWYDqJ=U72tamBTZC8A@mail.gmail.com"
type="cite">
<div dir="ltr">
<div>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.</div>
</div>
</blockquote>
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? <br>
<br>
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.<br>
<br>
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.<br>
<br>
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.<br>
<br>
Best Regards<br>
Georg<br>
<br>
<blockquote
cite="mid:CACsJT9PF4Fh0Yi+Y7RLADScUfAT-ND4aWYDqJ=U72tamBTZC8A@mail.gmail.com"
type="cite">
<div class="gmail_extra"><br>
<div class="gmail_quote">On 24 November 2014 at 12:39, Dirk
Thomas <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:dthomas@osrfoundation.org" target="_blank">dthomas@osrfoundation.org</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">We don't have to "develop" .roswiki files -
we already have a very similar feature: the doc jobs.
<div><br>
</div>
<div>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.</div>
<div>It is not only about API documentation - you can put
arbitrary content in it which some packages already do
make use of.</div>
<span class="HOEnZb"><font color="#888888">
<div><br>
</div>
<div>- Dirk</div>
</font></span></div>
<div class="HOEnZb">
<div class="h5">
<div class="gmail_extra"><br>
<div class="gmail_quote">On Mon, Nov 24, 2014 at 8:52
AM, Miquel Massot Campos <span dir="ltr"><<a
moz-do-not-send="true"
href="mailto:miquel.massot@gmail.com"
target="_blank">miquel.massot@gmail.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">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.
<div>
<div><br>
</div>
<div>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.</div>
</div>
</div>
<div class="gmail_extra"><br clear="all">
<div>
<div>
<div dir="ltr">
<div>
<blockquote style="margin:0 0 0
40px;border:none;padding:0px">Miquel
Massot</blockquote>
<div>
<div><a moz-do-not-send="true"
href="mailto:miquel.massot@gmail.com"
target="_blank">miquel.massot@gmail.com</a> <a
moz-do-not-send="true"
href="https://github.com/miquelmassot"
target="_blank"><img
moz-do-not-send="true"
src="http://ncuillery.github.io/angular-breadcrumb/img/GitHub-Mark-16px.png"></a></div>
</div>
<div><br>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<br>
<div class="gmail_quote">2014-11-24 17:39
GMT+01:00 Mike Purvis <span dir="ltr"><<a
moz-do-not-send="true"
href="mailto:mpurvis@clearpathrobotics.com"
target="_blank">mpurvis@clearpathrobotics.com</a>></span>:<br>
<blockquote class="gmail_quote"
style="margin:0 0 0 .8ex;border-left:1px
#ccc solid;padding-left:1ex">
<div dir="ltr">Some of what you want
already exists:
<div><br>
<div><a moz-do-not-send="true"
href="https://github.com/ros/ros_tutorials"
target="_blank">https://github.com/ros/ros_tutorials</a><br>
</div>
<div><a moz-do-not-send="true"
href="https://github.com/ros/geometry_tutorials"
target="_blank">https://github.com/ros/geometry_tutorials</a><br>
</div>
</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>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).</div>
<div>
<div>
<div><br>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">On 24
November 2014 at 11:29, Miquel
Massot Campos <span dir="ltr"><<a
moz-do-not-send="true"
href="mailto:miquel.massot@gmail.com"
target="_blank">miquel.massot@gmail.com</a>></span>
wrote:<br>
<blockquote
class="gmail_quote"
style="margin:0 0 0
.8ex;border-left:1px #ccc
solid;padding-left:1ex">
<div dir="ltr">+1 to mix and
match wiki-editable with
source-controlled wiki
content.
<div><br>
</div>
<div>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 "<i>tutorials</i>"
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... </div>
<div><br>
</div>
<div>However, what if a
developer wants to write
tutorials without fully
compilable code? I think
that the tutorials can
be placed in the .<i>roswiki</i>
file along with the
package documentation as
well as in compilable <i>pkg_tutorials</i>.
Another mix&match.</div>
<div><br>
</div>
<div><br>
</div>
</div>
<div class="gmail_extra"><br
clear="all">
<div>
<div>
<div dir="ltr">
<div>
<blockquote
style="margin:0
0 0
40px;border:none;padding:0px">Miquel
Massot</blockquote>
<div>
<div><a
moz-do-not-send="true"
href="mailto:miquel.massot@gmail.com" target="_blank">miquel.massot@gmail.com</a> <a
moz-do-not-send="true" href="https://github.com/miquelmassot"
target="_blank"><img
moz-do-not-send="true"
src="http://ncuillery.github.io/angular-breadcrumb/img/GitHub-Mark-16px.png"></a></div>
</div>
<div><br>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<br>
<div
class="gmail_quote">2014-11-24
16:42 GMT+01:00 Mike
Purvis <span
dir="ltr"><<a
moz-do-not-send="true"
href="mailto:mpurvis@clearpathrobotics.com" target="_blank">mpurvis@clearpathrobotics.com</a>></span>:<br>
<blockquote
class="gmail_quote"
style="margin:0 0
0
.8ex;border-left:1px
#ccc
solid;padding-left:1ex">
<div dir="ltr">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.
<div><br>
</div>
<div>This allows
the
flexibility to
mix and match
wiki-editable
content where
that is
appropriate
with blobs of
source-controlled
content, where
<i>that</i> is
more
appropriate.
It also offers
a sane
migration
strategy.</div>
<div><br>
</div>
<div>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.</div>
</div>
<div
class="gmail_extra"><br>
<div
class="gmail_quote">
<div>
<div>On 24
November 2014
at 10:18,
Jonathan
Bohren <span
dir="ltr"><<a
moz-do-not-send="true" href="mailto:jonathan.bohren@gmail.com"
target="_blank">jonathan.bohren@gmail.com</a>></span>
wrote:<br>
</div>
</div>
<blockquote
class="gmail_quote"
style="margin:0
0 0
.8ex;border-left:1px
#ccc
solid;padding-left:1ex">
<div>
<div>
<div
class="gmail_quote"><span>On
Mon Nov 24
2014 at
3:38:46 AM
Miquel Massot
Campos <<a
moz-do-not-send="true" href="mailto:miquel.massot@gmail.com"
target="_blank">miquel.massot@gmail.com</a>>
wrote:<br>
<blockquote
class="gmail_quote"
style="margin:0
0 0
.8ex;border-left:1px
#ccc
solid;padding-left:1ex">
<div dir="ltr">
<div>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 "<i>something.roswiki"</i> so
that the
documentation
generator<span
style="font-size:13.6000003814697px"> </span></div>
</div>
</blockquote>
<blockquote
class="gmail_quote"
style="margin:0
0 0
.8ex;border-left:1px
#ccc
solid;padding-left:1ex">
<div dir="ltr">
<div>pastes it
into the
roswiki?<span
style="font-size:13.6000003814697px"> </span></div>
</div>
</blockquote>
<div> </div>
</span>
<div><span
style="font-size:13.6000003814697px">I
agree. The
wiki is
broken, and
package
documentation
should reside
in the
packages
wherever the
code is
hosted.</span></div>
<div><span
style="font-size:13.6000003814697px"><br>
</span></div>
<div><span
style="font-size:13.6000003814697px">Unfortunately,
as Dirk said,
"</span><span
style="font-size:13.6000003814697px;line-height:15.8399991989136px">whatever
change you
propose must
be implemented
by someone."</span><span
style="font-size:13.6000003814697px"> So, I'm asking directly:</span></div>
<div><span
style="font-size:13.6000003814697px"><br>
</span></div>
<div><span
style="font-size:13.6000003814697px">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?</span></div>
<span><font
color="#888888">
<div><br>
</div>
<div><span
style="font-size:13.6000003814697px">-j</span></div>
</font></span></div>
<br>
</div>
</div>
<span>_______________________________________________<br>
ros-users
mailing list<br>
<a
moz-do-not-send="true"
href="mailto:ros-users@lists.ros.org" target="_blank">ros-users@lists.ros.org</a><br>
<a
moz-do-not-send="true"
href="http://lists.ros.org/mailman/listinfo/ros-users" target="_blank">http://lists.ros.org/mailman/listinfo/ros-users</a><br>
<br>
</span></blockquote>
</div>
<br>
</div>
<br>
_______________________________________________<br>
ros-users mailing
list<br>
<a
moz-do-not-send="true"
href="mailto:ros-users@lists.ros.org" target="_blank">ros-users@lists.ros.org</a><br>
<a
moz-do-not-send="true"
href="http://lists.ros.org/mailman/listinfo/ros-users" target="_blank">http://lists.ros.org/mailman/listinfo/ros-users</a><br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</div>
<br>
_______________________________________________<br>
ros-users mailing list<br>
<a moz-do-not-send="true"
href="mailto:ros-users@lists.ros.org"
target="_blank">ros-users@lists.ros.org</a><br>
<a moz-do-not-send="true"
href="http://lists.ros.org/mailman/listinfo/ros-users"
target="_blank">http://lists.ros.org/mailman/listinfo/ros-users</a><br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</div>
<br>
_______________________________________________<br>
ros-users mailing list<br>
<a moz-do-not-send="true"
href="mailto:ros-users@lists.ros.org"
target="_blank">ros-users@lists.ros.org</a><br>
<a moz-do-not-send="true"
href="http://lists.ros.org/mailman/listinfo/ros-users"
target="_blank">http://lists.ros.org/mailman/listinfo/ros-users</a><br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</div>
<br>
_______________________________________________<br>
ros-users mailing list<br>
<a moz-do-not-send="true"
href="mailto:ros-users@lists.ros.org"
target="_blank">ros-users@lists.ros.org</a><br>
<a moz-do-not-send="true"
href="http://lists.ros.org/mailman/listinfo/ros-users"
target="_blank">http://lists.ros.org/mailman/listinfo/ros-users</a><br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</div>
<br>
_______________________________________________<br>
ros-users mailing list<br>
<a moz-do-not-send="true"
href="mailto:ros-users@lists.ros.org">ros-users@lists.ros.org</a><br>
<a moz-do-not-send="true"
href="http://lists.ros.org/mailman/listinfo/ros-users"
target="_blank">http://lists.ros.org/mailman/listinfo/ros-users</a><br>
<br>
</blockquote>
</div>
<br>
</div>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
ros-users mailing list
<a class="moz-txt-link-abbreviated" href="mailto:ros-users@lists.ros.org">ros-users@lists.ros.org</a>
<a class="moz-txt-link-freetext" href="http://lists.ros.org/mailman/listinfo/ros-users">http://lists.ros.org/mailman/listinfo/ros-users</a>
</pre>
</blockquote>
<br>
<br>
<pre class="moz-signature" cols="72">--
.........................................................
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
<a class="moz-txt-link-abbreviated" href="mailto:heppner@fzi.de">heppner@fzi.de</a>
<a class="moz-txt-link-abbreviated" href="http://www.fzi.de">www.fzi.de</a>
.........................................................
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
.........................................................</pre>
</body>
</html>