Decide document location (rtm-ros, Hiro, Nextage) about rtmros_nextage

[130s]

Proposal:

• rtmros, hiro --> code.google.com
• Nextage --> wiki.ros.org

[k-okada]

wiki.ros.orgはデータは手元におけるんでしたっけ？
リビジョン管理などをかんがえると，ソースツリーと同じ所にドキュメントがあると
便利だとはおもうんですよね．
mainpage.dox
はそのひとつだし，前は僕達は
http://ftp.isr.ist.utl.pt/pub/roswiki/doc/api/jsk_tools/html/
というのを提唱していました．

今はどうなっているのかな．caktinなんかは別のdocumentationシステムになっていそうです．

[k-okada]

http://docs.ros.org/independent/api/rosdep/html/
なんかは上でやっていたjsk_toolsのlaunchdocとにていて，
多分rosのdocサーバみたいなことrでsphinxを動かして
ドキュメントを生成しているかんじです．
こうすると，
ソースとドキュメントを同じツリーで管理できている気がします．

[130s]

以前すこし調べた結果がここにあります．

確かに ros wiki に書くのは，backup は自分で取ってやらないと取れないので気が引けて，なるべく package.xml に書くようにしちゃってますが，xml 内に html を埋めるのを素手でやるので面倒；rst とか簡単な記法で書きたい．でも ros wiki は割と美しく表示されるから個人的に見た目が好きなのです，ROS に特化した macro もそれなりに充実しているし．それに，ユーザがある package に関する情報を取りに行くのは一箇所が望ましいので，ros wiki から github pages に飛ばすのも理想的ではない．うーむ．

[k-okada]

ヤマカンですが，https://github.com/ros/catkinをみてみると，
package.xmlで

  <export>
    <rosdoc config="rosdoc.yaml"/>
  </export>

と書いておいて，
https://github.com/ros/catkin/blob/groovy-devel/rosdoc.yaml　で doc ディレクトリを参照する．
すると，
http://docs.ros.org/hydro/api/catkin/html/
が出来るようにおもいます．doc以下にドキュメントもおけますが，どうもコードから生成している部分
http://docs.ros.org/hydro/api/catkin/html/dev_guide/api/catkin.html
もありそうです．

[130s]

どうやらそうっぽいですね．レポジトリでドキュメントも管理できるのはナイス．

これらの懸念とどう折り合いをつけるか：

• wiki の手軽さを失う
• macro が使えない
  • moinmoin (他の package のページにリンクを貼るのに，現状だと二重括弧内に package 名だけ書けば良い．楽)
  • ros wiki 独自のそれ
• 閲覧者はリンクを辿る手間が増える (ros package のドキュメントの入り口は ros wiki であることは変わらない)

[130s]

最近 bloom は https://read-the-docs.readthedocs.org/en/latest/getting_started.html に乗り換えたようです．github にアップロードすると自動的に html を生成してくれるような．ナイスですがいづれにせよ上に書いた懸念は変わらない．．
理想的なのは mainpage.dox のような，パッケージ内の doc ファイルを ros wiki が読み込んでくれることですかねえ．．

[k-okada]

優先順位としては

1. in-source documentation　→　ソースと文章の乖離の阻止
2. wikiの手軽さ→だれでも編集できる？
3. ros向けのmacro
   みたいなかんじでしょうか．

readthedocs はwikiではないけど，github上で編集するということで，そこそこ手軽なのかな．code APIみたいなもも統合されていたりするのかな．ただ，枯れたものでないと半年後には新しい物が出てきました，といって乗り換えていく体力はないので，要注意ですが．ただこういうのがでてきた，ということではdoc以下にファイルを作っておいて，あとはその時におうじて表示ツール（サービス）を選べばいいという気もしますね．

理想的なのは mainpage.dox のような，パッケージ内の doc ファイルを ros wiki が読み込んでくれることですかねえ．．

はいい気がしますね．

[k-okada]

githubの使い方，みたいな話を，
http://wiki.ros.org/rosdistro/Tutorials/Indexing%20Your%20ROS%20Repository%20for%20Documentation%20Generation
みたいな，チュートリアルがあるといいなとおもいました．
rtmros_commonのREADME.mdに書いて，ほかのパッケージはそこを参照するようにする，というかんじでしょうか？　あるいは，mdは，roswikiに飛ぶだけにしたほうが良さそうでしょうか？

[k-okada]

https://github.com/k-okada/rtmros_common/blob/master/README.md に簡単なgithub使い方を書きました．より詳しい方法は追加しておいて下さい．@garaemon

@mmurooka pull request お願いします．

[garaemon]

他人の変更を自分のgitに取り込む方法について追加しておきました

k-okada/rtmros_common#1

[130s]

Looks like rosdoc.yaml and mainpage.dox are still functionally converted to html.

Just found an example.
https://github.com/ros-controls/ros_control/blob/hydro-devel/transmission_interface/mainpage.dox
becomes
http://docs.ros.org/hydro/api/transmission_interface/html/c++/

[garaemon]

README.mdなどのmarkdownファイルの利点について

• コードと同じところで管理されてる。つまりプルリクにドキュメントの変更も含めることができる
  • すぐにwebで見られるの良い、reviewしやすい
  • 単純に楽しい、githubのcss綺麗. スマホでもみれる
  • 詳細なコードのドキュメントはコード内部に書くとして、概要をmarkdownファイルに書くのは有用と思われる

[garaemon]

travisからwiki.ros.org叩いて自動的にdeployできないものか？

[130s]

moinmoin, the wiki engine that ROS wiki runs on, seems to have rst support, although not vigorously active. Example.

So if we can ask ROS wiki maintainers to install docutils (I assume it's already installed, or it's not a problem) and also create a script (maybe integrated into an automation tool like rosdoc_lite), we can realize what's been discussed here (I have no time to take any action for it though).

[130s]

Thought about using github wiki and my answer is no.

Simply because the wiki pages are cloned SEPARATEly from its contents. I.e.,

$ git clone [email protected]:myusername/foobar.git
$ git clone [email protected]:myusername/foobar.wiki.git

(source)

In this way there's not much advantage of having doc on github.

ros_control seems to be struggling too in where to store documents. They use ros wiki, rosdoc_lite, and github wiki. Maybe @davetcoleman has ideas after having gone through all of these.

[130s]

And @k-okada summarized what we want.

[davetcoleman]

if we can directory convert readme.rst to wiki page, that's great, but seems difficult.

I really like that idea. I have made a lot of roswiki edits, but I do not like the format. It has some benefits, but many downfalls. Also, the roswiki is running on a very slow system that was not intended to grow to the size it is today. It is overdue for replacement.

I am currently a fan of always using Github README and just having a link on the roswiki to the readme (see moveit_simple_grasps).

Sorry for the late reply!

[130s]

Looks like Gazebo tutorials are written and stored in repository as md files, then the web page are generated from them?
e.g.

• web page http://gazebosim.org/tutorials?tut=ros_installing&cat=connect_ros
• md file https://bitbucket.org/osrf/gazebo_tutorials/src/default/ros_installing/tutorial.md

[davetcoleman]

MoveIt! is the same:
https://github.com/ros-planning/moveit_ros/blob/indigo-devel/visualization/doc/tutorial.rst

[k-okada]

how do you turn md file into web pages? it seems you do not use gh-pages.

On Sun, Sep 21, 2014 at 1:41 AM, Dave Coleman [email protected]
wrote:

MoveIt! is the same:

https://github.com/ros-planning/moveit_ros/blob/indigo-devel/visualization/doc/tutorial.rst

—
Reply to this email directly or view it on GitHub
#12 (comment)
.

[davetcoleman]

Good question... @hersh or @sachinchitta

[hersh]

md stands for "markdown", possibly originally from here: http://daringfireball.net/projects/markdown/

I've been happiest with our documentation when it is stored in the same repo as the source it refers to, so it's easy to keep synchronized.

[davetcoleman]

I think the question is, what component does MoveIt! use to convert md files into html?

[hersh]

MoveIt! doesn't have md files, except for the README.md files at the top of each repository. Those are converted to html by github on the main page for each repo.

[hersh]

Moveit has some documentation in rst files, which are similar to md files. Those are converted using sphinx via rosdoc.

[davetcoleman]

Ah yes, I meant the .rst files.

Those are converted using sphinx via rosdoc

Exactly what I was asking, thanks. So to update them a bloom-release is necessary, right?

[hersh]

Actually, no.

If the repo is already set up and built with the ROS build system by OSRF, the docs will just show up a few days after you push them to each main branch: hydro-devel, indigo-devel, etc.

[k-okada]

I see, so moveit tutorial means http://moveit.ros.org/documentation/tutorials/, not http://moveit.ros.org/wiki/Tutorials

And contents of http://moveit.ros.org/documentation/tutorials/ link to API doc in ros.org http://docs.ros.org/hydro/api/pr2_moveit_tutorials/html/index.html

[davetcoleman]

Correct

[130s]

Thanks @hersh @davetcoleman for the insight about moveit wiki. I thought it's worth extending the conversation to somewhere more public, so I did.

[130s]

Looks like @jbohren's ROS Index beat us to it!

[jbohren]

@130s What were you guys trying to do exactly?

[130s]

@jbohren sorry to pull you in late. I was suggesting to keep document only in each package's repository, and wondering if we can propagate the content into wiki.ros.org. ROS Index reading readme.md perfectly addresses this question (and does many other nice things too).

Not sure about any possible integration plan of ROS Index and ROS wiki though. If there's a plan I support that.