| Note: First create your own ROS repository using the RecommendedRepositoryUsage page. This tutorial assumes that you have completed the previous tutorials: Once you've created your own ROS package repository, you can document your stacks and packages on ROS.org.. |
 Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags. |
生成文档索引你的ROS存储库
Description: 世界各地的公司、大学和个人都有数百个ROS储存库。无论你发布的是一个ROS包还是数百个，都可以创建自己的存储库，与社区的其他成员共享代码。Tutorial Level: INTERMEDIATE
这是一个仅为文档编制索引的教程。要使一个版本进入二进制版本，请参阅cn/bloom文档。
Contents
生成文档索引你的ROS存储库
一旦你创建了自己的ROS包存储库，你就可以在ROS.org上记录你的栈和包了。
添加你的包到索引器，你能得到什么
(这张图片是可编辑的 这里.)
你功能包package.xml里面的信息会被解析，随后会自动生成wiki界面 (查看以上图片).
- (非常好的) 影响; 拉取信息会帮助因特网搜索引擎索引到你的界面，会有一个好的可见性。
首次为包添加到索引器
将你的存储库添加到索引器的步骤
首先， 在GitHub https://github.com/ros/rosdistro 上fork以下存储库
更多关于fork!GitHub 存储库的信息: https://help.github.com/articles/fork-a-repo
- 检查你fork的副本存储库进行编辑
git clone git@github.com:my_github_name/rosdistro.git
- 在你复制的rosdistro存储库的副本中，浏览到你想要更新的分发目录。
cd rosdistro/<DISTRO_NAME>
在这个目录中，编辑distribution.yaml文件并添加你的存储库信息(同时保持存储库的字母顺序)和doc部分。
- 存储库url应该指向上游存储库，而不是发布存储库。
可选地，你的存储库条目可以包含一个依赖(depends)值，该值包含你的代码(以及它的文档)所依赖的这个文件中列出的其他存储库名称的列表，但是你不想在与存储库关联的作业中显式地记录这些名称
- 运行以下脚本，在你当前rosdistro的根目录中，使你的文件符合rosdistros的特殊格式规则。它会改变文件的位置，所以如果你想要额外的安全，你可以备份你以前的改变。
rosdistro_reformat file://$(pwd)/index.yaml
- 在提交更改之前验证您的更改。
git diff distribution.yaml
git commit -m "Adding my_repo_name to documentation index for distro" distribution.yaml
Push你的改变到你远程的 GitHub 存储库 git push origin master
在GitHub上，提交一个pull request到rosdistro目录，用于添加你的rosinstall到索引器。
为你的包创建一个wiki页面短步骤
- 创建一个wiki.ros.org帐户，如果必要的话，登录。
- 输入你想要创建的页面的url。
例如： 你的包"your_package"的wiki界面为"http://wiki.ros.org/your_package" .
- 上面打开的页面会说页面不存在，从列表中选择适当的模板来创建页面。
对于包界面，选择"PackageTemplate".
同时我们鼓励你创建使用文档、教程、概述或者其他你想要的内容。查看编写包界面指南
就是这样!一旦你的pull请求得到了回复，你的rosinstall文件的文档将在下一次文档作业运行时生成。
从上游引入变更
当上游github.com/ros/rosdistro发生变化，需要pull更新时，你需要添加另外一个远程
git remote add upstream https://github.com/ros/rosdistro.git
现在，要改变别人已经做出的改变，需要注释ROS到github:
git pull upstream
Git将从上游提取更改，并将它们自动合并到当前分支中。这一步可能不会通知你本地repo和上游之间的冲突。在使用该分支时，你可能需要标识一个分支:}
另一种选择是两个步骤:
git fetch upstream
git merge upstream/master
如果你的本地回环和上游之间存在任何冲突，这两个步骤将提示你。
检查索引器是否程序索引到你的ROS包
对于任何你添加的目标/包/堆栈和在Jenkins服务器上创建的文档工作: http://build.ros.org/ (这个可能会在添加后进行更新)
只需在搜索框中输入元/包/堆栈名称即可找到相应的工作。在作业页面上，可以检查状态、失败消息和完整的控制台输出。
在ROS.org上编辑你包存储库文档
一旦你的存储库被索引到，一夜之间，文档作业被重新创建和运行。
为你的包创建一个wiki页面已经在上面解释过了。要在那里添加文档，下面的指南可以帮助你开始记录wiki:
一些好的wiki文档示例:
宣布你的包
在ros.org索引后, 你的包在全球社区中比以往任何时候都更加可见。有些人可能通过Google或ROS wiki的包查找搜索到你的包。这是好事，然后让人们知道你的工作(可以查看关于公告如何帮助讨论).
这样做只是简单地在discourse.ros.org的"`general`"类别上做一个新的帖子.
如果你对已经发布的软件包有一个值得注意的更新，那么它的公告也会被欣赏。
宣布新包模板
如果你想知道在公告中包含什么内容，你可以补充:
- 包名.
- 对包的简要描述(这可以是您的package.xml的一个副本)。顺便说一句!，不要忘记在包的package.xml中添加description。
在wiki.ros.org链接包 (在这个类似的wiki有解释).
- 连接到存储库, 虽然创建wiki页面非常受鼓励。
- 如果存在连接到教程。
- 对周期的承认，值得注意的是，如果有的话。
你可以在这里找到此前的许多具体的例子.