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

  1. 生成文档索引你的ROS存储库
    1. 添加你的包到索引器，你能得到什么
    2. 首次为包添加到索引器
      1. 将你的存储库添加到索引器的步骤
      2. 为你的包创建一个wiki页面短步骤
    3. 从上游引入变更
  2. 检查索引器是否程序索引到你的ROS包
  3. 在ROS.org上编辑你包存储库文档
  4. 宣布你的包
    1. 宣布新包模板

生成文档索引你的ROS存储库

一旦你创建了自己的ROS包存储库，你就可以在ROS.org上记录你的栈和包了。

添加你的包到索引器，你能得到什么

wiki.ros.org_packageHeader.png

(这张图片是可编辑的 这里.)

  • 你功能包package.xml里面的信息会被解析，随后会自动生成wiki界面 (查看以上图片).

  • (非常好的) 影响; 拉取信息会帮助因特网搜索引擎索引到你的界面，会有一个好的可见性。

首次为包添加到索引器

将你的存储库添加到索引器的步骤

  • 首先， 在GitHub https://github.com/ros/rosdistro 上fork以下存储库 rosdistro_fork.png

  • 检查你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到索引器。rosdistro_pull.png rosdistro_pull_submit.png

    • pull请求的具体示例: 1, 2

为你的包创建一个wiki页面短步骤

  1. 创建一个wiki.ros.org帐户，如果必要的话，登录。
  2. 输入你想要创建的页面的url。

    • 例如： 你的包"your_package"的wiki界面为"http://wiki.ros.org/your_package" .

  3. 上面打开的页面会说页面不存在，从列表中选择适当的模板来创建页面。

    • 对于包界面，选择"PackageTemplate".

  4. 同时我们鼓励你创建使用文档、教程、概述或者其他你想要的内容。查看编写包界面指南

就是这样!一旦你的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 pull upstream master}

另一种选择是两个步骤:

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页面非常受鼓励。
  • 如果存在连接到教程。
  • 对周期的承认，值得注意的是，如果有的话。

你可以在这里找到此前的许多具体的例子.

Wiki: cn/rosdistro/Tutorials/Indexing Your ROS Repository for Documentation Generation (last edited 2018-03-24 08:01:40 by Playfish)

Except where otherwise noted, the ROS wiki is licensed under the
Creative Commons Attribution 3.0