mk.docs.nav2.org

Installation

Virtual Environment

Install pip and venv if not already installed:

sudo apt install python3-pip python3-venv

Create a virtual environment and activate it:

python3 -m venv venv &&
source venv/bin/activate

Install all required dependencies:

pip3 install -r requirements.txt

Docker Container

Build the Docker image (from this directory):

docker build -f Dockerfile --build-arg user=$(id -un) --build-arg uid=$(id -u) -t nav2_docs .

To build the documentation:

docker run --rm -v .:/docs nav2_docs mkdocs build

To run autobuild (watches for changes and rebuilds automatically):

docker run --init --rm -it -v .:/docs -p 127.0.0.1:8000:8000 nav2_docs mkdocs serve --dev-addr 0.0.0.0:8000

Then browse to http://127.0.0.1:8000. Use Ctrl+C to stop (the --init flag enables proper signal handling).

Using VS Code Dev Container

If you're using Visual Studio Code, you can use the dev container for an easy setup:

1. Install the Dev Containers extension
2. Open this folder in VS Code
3. When prompted, click "Reopen in Container" (or use Command Palette: Dev Containers: Reopen in Container)
4. Once the container is built and running, use the integrated terminal to build the docs

The dev container automatically sets up all dependencies. You can then use the build commands described below.

Build

Single distribution

Use the following command from the required distribution branch to build the documentation:

mkdocs build

The build result can be found in the site directory, and the entry point in site/index.html file. Other options for the build command.

Instead of the usual build process, MkDocs provides a live preview server that can be started with:

mkdocs serve

It allows to preview new changes during documentation update. The server will automatically rebuild the entire documentation after each file saving and display result at http://127.0.0.1:8000/. See more options for the command.

Warning

The command mkdocs serve will display documentation for only one distribution without the ability to switch between them.
To preview multiple distributions, follow the instructions below.

Multiple distributions

The current documentation relies on the mike utility to support multiple versions. To build the documentation, execute the following command from the corresponding <distribution> branch for each version that needs to be displayed:

mike deploy <distribution>

After execution, a new directory with the selected <distribution> name will be created on the local gh-pages branch. This directory will also contain the build result with the corresponding entry point <distribution>/index.html. In addition, it creates the same site directory as before using mkdocs build in the current branch.

You can set the --title option to change the version name displayed on the website. See more options for this command.

Example for two branches:

• Execute from rolling branch:

  mike deploy rolling --title=Rolling

• Execute from jazzy branch:

  mike deploy jazzy --title=Jazzy

Before viewing, you need to set the default version:

mike set-default <distribution>

Similar to mkdocs serve, mike provides a server that can be started with:

mike serve

The documentation will be available at the same address http://127.0.0.1:8000/, and each version at the corresponding address http://127.0.0.1:8000/<distribution>/.
See more options for this command.

Note

This server does not provide a live preview after changes are made locally.
To display the new changes, use the mike deploy command for the corresponding branch, as was shown before.

This command is useful for local testing and viewing differences between versions without the need to use a real web server. If you need to make changes for only one version, it will be more convenient to use mkdocs serve for this purpose, due to its live preview ability.

After completing all changes, use these commands to exit the working environment:

• If using the virtual environment (venv):

  deactivate

• If using the VS Code Dev Container:

  Select in the Command Palette: Dev Containers: Reopen Folder Locally

License

This project is licensed under the terms of the Apache-2.0 license.
Any images, diagrams, or videos are subject to their own copyrights, trademarks, and licenses.