From 3e598e25d90d286e444153ff60d7b6e82f0f209f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Steven!=20Ragnar=C3=B6k?= Date: Wed, 17 Jul 2024 14:33:41 -0700 Subject: [PATCH] Update install instructions. (#130) * Document rosdoc2 installation via ROS repositories. I also removed the instruction to install ros2_documentation dependencies as any actual dependencies of rosdoc2 should be listed as dependencies in setup.cfg (for pypi dependencies) and stdeb.cfg (for python and system dependencies) and installed with the apt package. * Add alternative installation instructions. rosdoc2 can also be installed from pypi, which would be useful on a non-Debian / -Ubuntu platform like Fedora or macOS. Since the doc jobs on the build farm currently use rosdoc2 @ main I also included instructions for installing it from source via pip. Both methods recommend using virtualenvs and link to upstream documentation for doing so. I'm not opposed to adding `pipx` instructions or hints as well since this project includes tests for it, but `pipx` is not a tool that's currently recommended by the Open Robotics Infrastructure project and the preferred installation method will be the ROS apt repositories. --- README.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f76df90..2bcb366 100644 --- a/README.md +++ b/README.md @@ -46,24 +46,29 @@ Additionally, if you have a Python API then you will want to provide a Sphinx `c ## Installation -### Prerequisite +`rosdoc2` can be installed from the [ROS repositories](https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debians.html#enable-required-repositories). ``` -apt install -y python3-pip git +apt install -y python3-rosdoc2 ``` -and then, install [ros2_documentation](https://github.com/ros2/ros2_documentation?tab=readme-ov-file#prerequisites) required packages. +#### Installation from PyPI -### `rosdoc2` installation - -`rosdoc2` can be installed locally from the git repository. -Clone the repository, change into the directory, and then run: +You may also install rosdoc2 from [PyPI](https://pypi.org/project/rosdoc2). +If you do so, we recommend you install and use it from a [virtualenv][]. ``` -pip install --user --upgrade . +python3 -m pip install rosdoc2 ``` -`rosdoc2` will be installed under `~/.local/bin/` directory. +#### Installation from source + +You can also use pip to install rosdoc2 from source. +Again, we recommend you install and use it from a [virtualenv][]. + +``` +python3 -m pip install --upgrade 'git+https://github.com/ros-infrastructure/rosdoc2@main' +``` ## Documentation @@ -230,3 +235,5 @@ TODO | 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. | + +[virtualenv]: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments