diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000000..4c3c2ceac6 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,19 @@ +{ + "name": "ROS 2 Documentation", + "build": { + "dockerfile": "../docker/image/Dockerfile" + }, + "workspaceMount": "source=${localWorkspaceFolder},target=/tmp/doc_repository,type=bind", + "workspaceFolder": "/tmp/doc_repository", + "postCreateCommand": "pip3 install --no-warn-script-location --user -r requirements.txt -c constraints.txt --break-system-packages", + "features": { + "ghcr.io/devcontainers/features/git:1": {} + }, + "customizations": { + "vscode": { + "extensions": [ + "ritwickdey.LiveServer" + ] + } + } +} \ No newline at end of file diff --git a/README.md b/README.md index 86ba153b96..7123c0f6a7 100644 --- a/README.md +++ b/README.md @@ -18,13 +18,21 @@ To build this you need to install * make * graphviz -* python virtualenv - -In the virtualenv +With [venv](https://docs.python.org/3/library/venv.html) ``` +# activate the venv +python3 -m venv ros2doc + +# activate venv +source ros2doc/bin/activate + +# install required packages pip install -r requirements.txt -c constraints.txt + +# deactivate the venv +(ros2doc) deactivate ``` ### Pinned versions @@ -36,6 +44,7 @@ To upgrade the system validate that things are working and then use `pip freeze ## Building HTML ### Local development test + For local testing of the current tree use: `make html` diff --git a/docker/image/Dockerfile b/docker/image/Dockerfile index af5cf7f6a2..fa00c3287a 100644 --- a/docker/image/Dockerfile +++ b/docker/image/Dockerfile @@ -3,13 +3,16 @@ # # docker build -f docker/image/Dockerfile . -FROM ubuntu:jammy +FROM ubuntu:noble ARG user=rosindex ARG uid=1000 ENV DEBIAN_FRONTEND noninteractive +# Delete user if it exists in container (e.g Ubuntu Noble: ubuntu) +RUN if id -u $uid ; then userdel `id -un $uid` ; fi + RUN apt-get update && \ apt-get install --no-install-recommends -y \ git-all \ @@ -30,4 +33,4 @@ WORKDIR /tmp/doc_repository USER $user -CMD pip3 install --no-warn-script-location --user -r requirements.txt -c constraints.txt && make multiversion +CMD pip3 install --no-warn-script-location --user -r requirements.txt -c constraints.txt --break-system-packages && make multiversion diff --git a/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst b/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst index c0b0ac0e42..500c443159 100644 --- a/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst +++ b/source/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.rst @@ -33,29 +33,37 @@ The root directory contains configuration and files required to locally build th Building the site locally ------------------------- -Start by installing requirements located in the ``requirements.txt`` file: +Start by creating `venv `__ to build the documentation: + +.. code-block:: console + + # activate the venv + python3 -m venv ros2doc + + # activate venv + source ros2doc/bin/activate + +And install requirements located in the ``requirements.txt`` file: .. tabs:: .. group-tab:: Linux - The next command does a user-specific install, which requires ``~/.local/bin/`` to be added to ``$PATH``: - .. code-block:: console - pip3 install --user --upgrade -r requirements.txt + pip install -r requirements.txt -c constraints.txt .. group-tab:: macOS .. code-block:: console - pip3 install --user --upgrade -r requirements.txt + pip install -r requirements.txt -c constraints.txt .. group-tab:: Windows .. code-block:: console - python -m pip install --user --upgrade -r requirements.txt + python -m pip install -r requirements.txt -c constraints.txt In order for Sphinx to be able to generate diagrams, the ``dot`` command must be available. @@ -232,6 +240,39 @@ Finally, to view the site, you can click on the "Go Live" button in the right bo :width: 100% :alt: Live Server +Building the Site with Devcontainer +----------------------------------- + +`ROS 2 Documentation GitHub repository `__ also supports ``Devcontainer`` development environment with Visual Studio Code. +This will enable you to build the documentation much easier without changing your operating system. + +See :doc:`../../How-To-Guides/Setup-ROS-2-with-VSCode-and-Docker-Container` to install VS Code and Docker before the following procedure. + +Clone repository and start VS Code: + +.. code-block:: console + + git clone https://github.com/ros2/ros2_documentation + cd ./ros2_documentation + code . + +To use ``Devcontainer``, you need to install "Remote Development" Extension within VS Code search in Extensions (CTRL+SHIFT+X) for it. + +And then, use ``View->Command Palette...`` or ``Ctrl+Shift+P`` to open the command palette. +Search for the command ``Dev Containers: Reopen in Container`` and execute it. +This will build your development docker container for you automatically. + +To build the documentation, open a terminal using ``View->Terminal`` or ``Ctrl+Shift+``` and ``New Terminal`` in VS Code. +Inside the terminal, you can build the documentation: + +.. code-block:: console + + make html + +.. image:: images/vscode_devcontainer.png + :width: 100% + :alt: VS Code Devcontainer + Writing pages ------------- diff --git a/source/The-ROS2-Project/Contributing/images/vscode_devcontainer.png b/source/The-ROS2-Project/Contributing/images/vscode_devcontainer.png new file mode 100644 index 0000000000..531294d583 Binary files /dev/null and b/source/The-ROS2-Project/Contributing/images/vscode_devcontainer.png differ