[ros-users] Wiki documentation for twist_mux package

[Jonathan Bohren]

On Fri, May 8, 2015 at 11:26 AM Mike Purvis <mpurvis at clearpathrobotics.com>
wrote:

> A few of us have been experimenting with various schemes for rendering
> docs and tutorials as static versioned pages rather than wiki content, cf.
>
> http://docs.ros.org/api/jackal_tutorials/html/
> http://docs.ros.org/indigo/api/robot_upstart/html/
> http://docs.ros.org/indigo/api/capabilities/html/
> http://unboundedrobotics.github.io/ubr1_preview/
>
> I was particularly happy with the sphinx-argparse plugin which is what renders
> the first big chunk of this page
> <http://docs.ros.org/indigo/api/robot_upstart/html/install.html>. I think
> there would be fantastic potential to develop a suite of Sphinx plugins
> which could automatically render decent quality docs from easily
> discoverable information (cfg files, launch files, etc).
>

I think this is definitely a more sustainable solution than the wiki, but
of course it still suffers from lack of visibility and fragmentation.


> William's got a more general discussion about where this should/could go
> in the future:
>
> http://design.ros2.org/articles/ros_documentation_system.html
>

Yeah, there's been a lot of discussion about these things. Unfortunately, I
disagree with some of the design priorities and implicit assumptions about
how the community operates. Instead of arguing about them and then waiting
for a solution that comes along with ROS2, I just built rosindex
<http://rosindex.github.io/>.

The pattern that I've observed is that someone will post on ros-users about
how the wiki isn't good enough, then a discussion will ensue for a week or
so in which a ton of people make statements that start off with "wouldn't
it be great if..." and "the ros wiki really should..." . Then someone from
OSRF steps in and says that these are all great ideas but there aren't any
resources to pursue them, and the conversation dies. Of course you can't
fault OSRF for saying this, since they have enough on their plate as it is.
But it was one of these threads that inspired me to put together rosindex
<http://rosindex.github.io>.

Since I don't work for OSRF, I can create this service in my free time and
I'm not responsible for making sure it satisfies everyone else's needs. I
can build it the way I see fit, and if it helps people, then that's a
success. If it's not helpful to you, you can either contribute, or just not
use it. I personally just want to be able to find and inspect released,
unreleased, and forked packages easily. I want to help people avoid
reinventing the wheel.

Fortunately, rosindex <http://rosindex.github.io> gets you pretty far
without requiring that anyone add anything special to their repositories.
It also doesn't assume that there's only one "true" version of a given
package. It fully supports forks and alternate packages with the same name.
It even detects launchfiles and extracts their arguments for display on the
page.

Anyone is welcome to take a look at the rosindex source, too:
https://github.com/rosindex/rosindex

-j
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-users/attachments/20150508/28bfa552/attachment.html>