<div dir="ltr"><div class="gmail_quote">On Fri, May 8, 2015 at 11:26 AM Mike Purvis <<a href="mailto:mpurvis@clearpathrobotics.com" target="_blank">mpurvis@clearpathrobotics.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">A few of us have been experimenting with various schemes for rendering docs and tutorials as static versioned pages rather than wiki content, cf.<div><br></div><div><a href="http://docs.ros.org/api/jackal_tutorials/html/" target="_blank">http://docs.ros.org/api/jackal_tutorials/html/</a><br></div><div><a href="http://docs.ros.org/indigo/api/robot_upstart/html/" target="_blank">http://docs.ros.org/indigo/api/robot_upstart/html/</a><br></div><div><a href="http://docs.ros.org/indigo/api/capabilities/html/" target="_blank">http://docs.ros.org/indigo/api/capabilities/html/</a><br></div><div><a href="http://unboundedrobotics.github.io/ubr1_preview/" target="_blank">http://unboundedrobotics.github.io/ubr1_preview/</a></div><div><br></div><div>I was particularly happy with the sphinx-argparse plugin which is what <a href="http://docs.ros.org/indigo/api/robot_upstart/html/install.html" target="_blank">renders the first big chunk of this page</a>. 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).</div></div></blockquote><div><br></div></div><div dir="ltr"><div class="gmail_quote"><div>I think this is definitely a more sustainable solution than the wiki, but of course it still suffers from lack of visibility and fragmentation. </div></div></div><div dir="ltr"><div class="gmail_quote"><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>William's got a more general discussion about where this should/could go in the future:</div><div><br></div><div><a href="http://design.ros2.org/articles/ros_documentation_system.html" target="_blank">http://design.ros2.org/articles/ros_documentation_system.html</a></div></div></blockquote><div><br></div></div></div><div dir="ltr"><div class="gmail_quote"><div>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 <a href="http://rosindex.github.io/">rosindex</a>.</div><div><br></div><div>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 <a href="http://rosindex.github.io">rosindex</a>.</div><div><br></div><div>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.</div><div><br></div><div>Fortunately, <a href="http://rosindex.github.io">rosindex</a> 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.</div></div></div><div dir="ltr"><div class="gmail_quote"><div><br></div><div>Anyone is welcome to take a look at the rosindex source, too:</div><div><a href="https://github.com/rosindex/rosindex">https://github.com/rosindex/rosindex</a></div><div><br></div><div>-j</div></div></div></div>