Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update install procedure and prerequisite. #67

Merged
merged 2 commits into from
Mar 17, 2024
Merged

update install procedure and prerequisite. #67

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0c09099
update install procedure and prerequisite.
fujitatomoya Mar 16, 2024
5485a29
add `Known Issues` section.
fujitatomoya Mar 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 25 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,21 @@ This tool can be viewed from two perspectives: first from the perspective of a u
To generate the documentation for almost any ROS 2 package, first build the package locally, then run this command replacing the arguments with appropriate directories:

```
$ rosdoc2 build \
rosdoc2 build \
fujitatomoya marked this conversation as resolved.
Show resolved Hide resolved
--package-path ./src/path/to/my_package_name
```

> [!NOTE]
> Please see [Known Issues](#known-issues) if failed.

This command will inspect your package and run various documentation tools based on the configuration of your package.

The package directory that you specify must contain a single ROS 2 package that has a `package.xml` file and optionally a YAML configuration file to configure the doc build process.

There will be an `index.html` file in the output directory which you can open manually, or with this command:

```
$ rosdoc2 open ./doc_output/index.html
rosdoc2 open ./doc_output/index.html
```

For more advanced usage see the documentation.
Expand All @@ -37,13 +40,25 @@ Additionally, if you have a Python API then you will want to provide a Sphinx `c

## Installation

### Prerequisite

```
apt install -y python3-pip git
```

and then, install [ros2_documentation](https://github.com/ros2/ros2_documentation?tab=readme-ov-file#prerequisites) required packages.

### `rosdoc2` installation

`rosdoc2` can be installed locally from the git repository.
Clone the repository, change into the directory, and then run:

```
$ pip install --user --upgrade .
pip install --user --upgrade .
```

`rosdoc2` will be installed under `~/.local/bin/` directory.

## Documentation

The purpose of this tool is to automate the execution of the various documentation tools when building documentation for ROS 2 packages.
Expand Down Expand Up @@ -98,7 +113,7 @@ How to do that, and how to handle some other special cases will follow.
To generate a default config file, run

```
$ rosdoc2 default_config \
rosdoc2 default_config \
--package-path ./src/path/to/my_package_name
```

Expand Down Expand Up @@ -182,3 +197,9 @@ TODO
## Contributing

TODO

## Known Issues

| Description / Error Message | Issue | Workaround |
|:---|:---:|:---|
| `No module named 'rclpy._rclpy_pybind11'` | [#66](https://github.com/ros-infrastructure/rosdoc2/issues/66) | Do not source colcon workspace. |
Loading