[Documentation] [TitleIndex] [WordIndex

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.

Indexing Your ROS Repository for Documentation Generation

Description: There are hundreds of ROS repositories hosted by companies, universities, and individuals around the world. Whether you're releasing one ROS package or hundreds, feel free to start your own repository to share your code with the rest of the community.

Tutorial Level: INTERMEDIATE

This is a tutorial for indexing for documentation only. To make a release into binary builds see the bloom documentation.

Indexing Your ROS package Repository for Documentation Generation

Once you've created your own ROS package repository, you can document your stacks and packages on ROS.org.

What you get by adding your package to the indexer


(this image is editable here.)

First time for a package to be added to the indexer

Steps to have your repository added to our indexer

Create a wiki page for your package in very short steps

  1. Create a wiki.ros.org account if necessary and log on.
  2. Enter into the wiki the url of the page you want to create.
    • e.g. "http://wiki.ros.org/your_package" for "your_package".

  3. The page opened above will say the page does not exist, select the appropriate Template from the list to create your page.
    • For a package, choose "PackageTemplate".

  4. We also encourage you to create usage documentation, tutorials, reviews, or whatever other content you want. See the guide to writing package documentation

That's it! Once your pull request is serviced, documentation for your rosinstall files will be generated the next time the documentation jobs run.

Pull in changes from upstream

To pull in changes from github.com/ros/rosdistro, you need to add another remote

git remote add upstream https://github.com/ros/rosdistro.git

Now to pull changes other people have made and ROS has commited to github:

git pull upstream

Git will pull changes from upstream and automatically merge them into your current branch. This single step could won't notify you of conflicts between your local repo and upstream. You may have to identify a branch when using this: git pull upstream master

An alternative is a two step process:

git fetch upstream

git merge upstream/master

This two step process will prompt you if there are any conflicts between your local repo and upstream.

Check for the indexer to successfully index your ROS package

For every meta/package/stack you add an document job is created on the Jenkins server: http://build.ros.org/ (this might take a while after adding)

Simply enter the meta/package/stack name in the search box to find corresponding jobs. On the job page the status, failure message and full console output can be inspected.

Documenting Your ROS package Repository on ROS.org

Once your repository has been indexed, overnight the documentation jobs are recreated and run.

Creating a wiki page for your package is already explained above. To add documentation there, the following guidelines help you get started with documenting on the wiki:

Some exemplars of good wiki documentation:

Announce your package

Being indexed on ros.org, your package has far more visibility than ever before among the global community. Some people may find your package through Google or ROS wiki's package search. It's always better, however, to let people know your work (see also a discussion about how announcement helps).

To do so simply make a new post on "`general`" category on discourse.ros.org.

If you have a notable update for a package that is already released, announcement for it is also appreciated.

Template for a new package announcement

If you wonder what to include in the announcement, you could add:

You can find many previous concrete examples.

2020-04-18 13:08