Skip to content

Commit 41ef588

Browse files
ruffslruffsl
authored
Add docs for Dev Containers (ros-navigation#407)
* Checkin work in progress * Add section on Security * Add description of container runtime and runArgs * Add to using dev container * Add subsection on Terminals * Add subsection on Lifecycle * Add reminder to Lifecycle about pushing to remote * Add subsection on Rebuilding * Rename file to own subtree * Enable markdown support for Sphinx https://stackoverflow.com/a/33797841/2577586 * Add dev_containers to root index * Fix missing URL * Spin out content into development guide to shorten the introduction * Add guides to index * Fix subheading levels to prevent warning as described here: https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html#document-structure * Add reference to using remote docker host as an alternative to codespaces * Update section Getting stared * Enalbe admonitions and callouts highlighting By adding "colon_fence" to myst_enable_extensions https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence * Use tip admonition * Use node admonition * Rewording * Fromatting * Use caution admonition * Use hint admonition * Wording * Wording * Formatting * Add section intros * Wording * Add seealso callout for Nav2 CI * Add hint callout for colcon extentions * Use attention admonition about runArgs * Update remarks on volumes to explain changes from: - ros-navigation/navigation2#3524 * Grammar * Update notes on current runArgs with added links for reference * Add seealso callout for details on used runArgs * Update remark about volumes * Formatting * Sort Formatting * Install sphinx_copybutton for handy copybutton - https://sphinx-copybutton.readthedocs.io/ * Simplify install instructions * Format install instructions * Wording * Add missing annotating in order to reference it elsewhare - https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html * Update build instructions * Update docker instructions * Default branch is sadly not named rolling would be consistently convenient if it was * Add descriptions for each build method * Wording * Expand docker docs with links * Formatting * Add note that rolling is tracked via main branch * Add tip for development workflow * Add attention to terminals * Add hint to terminals using the dropdown class as it isn't too significant * Add important to lifecycle * Add caution to rebuilding * Add details to rebuilding without cache * Add caution to rebuilding without cache * Add tip to rebuilding * Split Visualization Guide into separate PR * Use seealso admonition * Upgrade security caution to danger to stand out using the color red * Wording * Wording * Add tip about logfile the exact command name may change, so just hint about namespace instead - microsoft/vscode-remote-release#8018 * Typo * Comment out runArgs unintended side effects or cross talk between containers by default also avoids interfering with vscode's X11 forwarding * Wording * Update requirements.txt to match docs and CI * Add new dependencies * Fix version for new dependencies * Move development files to simplify onboarding * Update README to simply install using requirements.txt * Update Dockerfile to simply install using requirements.txt * Update CI to simply install using requirements.txt * Simplify Dockerfile * Simplify apt install * Expand apt install * Sort apt install * Prune apt install * Update Dockerfile to match CI for consistency and simplicity * Fix working_directory to find requirements.txt in PWD * Update attention to omit remarks about EOL distros * Avoid the use of export also helps keep the commands shell agnostic e.g. using another shell such as fish * Rewording * Refactor build and devcontainer docs * Set language to english to fix warnings - sphinx-doc/sphinx#10474 * Exclude README file from markdown pattern to fix warnings * Orphan files not included in any toctree to fix warnings - https://stackoverflow.com/a/40725923/2577586 * Stage renaming links * Rename indexs and headings * Use globe for hidden toctree * Add guide index for discoverability * Reorder caution admonition as a TLDR * Add body text to index * Combine contribute into development guide * Add hidden toctree without maxdepth to ensure build_instructions is included in the sidebar * Use seealso admonition for dev container links * Revert change to avoid duplicate toctree entries otherwise the sidebar navigation open duplicate dropdowns * Instal sphinx-autobuild * Add make build task and make it default * Add .dockerignore file * Add auto build option * Show all warning for better debugging * Add devcontainer config * Fix artifact path with respect to working_directory in docs_exec
1 parent 878d354 commit 41ef588

27 files changed

+639
-199
lines changed

‎.circleci/config.yml

+17-17
Original file line numberDiff line numberDiff line change
@@ -3,34 +3,34 @@ version: 2.1
33
references:
44
on_checkout: &on_checkout
55
checkout:
6-
path: nav2_docs
6+
path: .
77
setup_doc_dependencies: &setup_doc_dependencies
88
run:
99
name: Install Doc Dependencies
1010
command: |
1111
export DEBIAN_FRONTEND=noninteractive
1212
apt update
13-
apt install make -y
14-
apt install doxygen -y
15-
apt install graphviz -y
16-
apt install ttf-dejavu -y
17-
apt install openjdk-8-jre -y
18-
apt install bash git openssh-server -y
19-
apt install python3-pip python3 -y
20-
pip3 install sphinx==3.5.0 docutils==0.14 sphinx_rtd_theme breathe==4.28.0 sphinxcontrib-plantuml jinja2==3.0.3
13+
apt install -y \
14+
doxygen \
15+
git \
16+
graphviz \
17+
make \
18+
openjdk-8-jre \
19+
openssh-server \
20+
python3-pip \
21+
ttf-dejavu
22+
pip3 install -r requirements.txt
2123
make_docs: &make_docs
2224
run:
2325
command: |
24-
cd nav2_docs
2526
make html
2627
store_docs: &store_docs
2728
store_artifacts:
28-
path: nav2_docs/_build/html
29+
path: _build/html
2930
destination: html
3031
publish_docs: &publish_docs
3132
run:
3233
command: |
33-
cd nav2_docs
3434
make publish
3535
install_deployment_key: &install_deployment_key
3636
add_ssh_keys:
@@ -56,27 +56,27 @@ executors:
5656
docs_exec:
5757
docker:
5858
- image: ubuntu:focal
59-
working_directory: /
59+
working_directory: /nav2_docs
6060

6161
jobs:
6262
docs_build:
6363
executor: docs_exec
6464
steps:
65-
- install_doc_dependencies
6665
- *on_checkout
66+
- install_doc_dependencies
6767
- build_docs
6868
- persist_to_workspace:
69-
root: nav2_docs
69+
root: .
7070
paths:
7171
- _build
7272
docs_publish:
7373
executor: docs_exec
7474
steps:
75-
- install_doc_dependencies
7675
- *on_checkout
76+
- install_doc_dependencies
7777
- *install_deployment_key
7878
- attach_workspace:
79-
at: nav2_docs
79+
at: .
8080
- publish_docs_to_gh_pages_branch
8181

8282
workflows:

‎.devcontainer/devcontainer.json

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"name": "Nav2 Docs",
3+
"build": {
4+
"dockerfile": "../Dockerfile",
5+
"context": ".."
6+
},
7+
"workspaceMount": "source=${localWorkspaceFolder},target=/docs,type=bind",
8+
"workspaceFolder": "/docs",
9+
"onCreateCommand": ".devcontainer/on-create-command.sh",
10+
"updateContentCommand": ".devcontainer/update-content-command.sh",
11+
"customizations": {
12+
"vscode": {
13+
"settings": {},
14+
"extensions": [
15+
"eamodio.gitlens",
16+
"esbenp.prettier-vscode",
17+
"GitHub.copilot",
18+
"streetsidesoftware.code-spell-checker"
19+
]
20+
}
21+
}
22+
}

‎.devcontainer/on-create-command.sh

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#!/bin/bash
2+
3+
# Immediately catch all errors
4+
set -eo pipefail
5+
6+
# Uncomment for debugging
7+
# set -x
8+
# env
9+
10+
git config --global --add safe.directory "*"
11+
12+
.devcontainer/update-content-command.sh

‎.devcontainer/update-content-command.sh

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/bin/bash
2+
3+
# Immediately catch all errors
4+
set -eo pipefail
5+
6+
# Uncomment for debugging
7+
# set -x
8+
# env
9+
10+
# make clean
11+
# make html

‎.dockerignore

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
################################################################################
2+
# Repo
3+
4+
.circleci/
5+
.devcontainer/
6+
.dockerignore
7+
.git/
8+
.github/
9+
.gitignore
10+
.vscode/
11+
**.Dockerfile
12+
**Dockerfile
13+
_build/

‎.vscode/tasks.json

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{
2+
// See https://go.microsoft.com/fwlink/?LinkId=733558
3+
// for the documentation about the tasks.json format
4+
"version": "2.0.0",
5+
"tasks": [
6+
{
7+
"label": "Build",
8+
"icon": {
9+
"id": "gear"
10+
},
11+
"type": "shell",
12+
"command": "make html",
13+
"isBackground": false,
14+
"problemMatcher": [],
15+
"group": {
16+
"kind": "build",
17+
"isDefault": true
18+
}
19+
},
20+
{
21+
"label": "Autobuild",
22+
"icon": {
23+
"id": "debug-start"
24+
},
25+
"type": "shell",
26+
"command": "make autobuild",
27+
"isBackground": true,
28+
"problemMatcher": [],
29+
"group": {
30+
"kind": "build",
31+
"isDefault": false
32+
}
33+
}
34+
]
35+
}

‎2021summerOfCode/Summer_2021_Student_Program.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
:orphan:
2+
13
.. _summer_2021_student_program:
24

35

‎2021summerOfCode/projects/create_configuration_assistant.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
:orphan:
2+
13
.. _create_moveit_analog:
24

35
1. Create a Configuration Assistant (Analog to MoveIt)

‎2021summerOfCode/projects/create_plugins.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
:orphan:
2+
13
.. _create_plugins:
24

35

‎2021summerOfCode/projects/grid_maps.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
:orphan:
2+
13
.. _grid_maps:
24

35

‎2021summerOfCode/projects/localization.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
:orphan:
2+
13
.. _localization:
24

35

‎2021summerOfCode/projects/navigation_rebranding.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
:orphan:
2+
13
.. _rebranding:
24

35

‎Dockerfile

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
FROM ubuntu:focal
2+
3+
ARG DEBIAN_FRONTEND=noninteractive
4+
RUN apt update && \
5+
apt install -y \
6+
doxygen \
7+
git \
8+
graphviz \
9+
make \
10+
openjdk-8-jre \
11+
openssh-server \
12+
python3-pip \
13+
ttf-dejavu
14+
15+
COPY requirements.txt ./
16+
RUN pip3 install -r requirements.txt

‎Makefile

+6-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ else
88
endif
99

1010
# You can set these variables from the command line.
11-
SPHINXOPTS ?= -q
11+
SPHINXOPTS ?=
1212
SPHINXBUILD = sphinx-build
1313
SPHINXPROJ = "Nav2 Documentation"
1414
SOURCEDIR = .
@@ -35,6 +35,11 @@ help:
3535
html:
3636
$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O)
3737

38+
# Autobuild the docs on changes
39+
40+
autobuild:
41+
sphinx-autobuild -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS)
42+
3843
# Remove generated content (Sphinx and doxygen)
3944

4045
clean:

‎README.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,13 @@ https://navigation.ros.org/
44
This folder holds the source and configuration files used to generate the
55
[Navigation2 documentation](https://navigation.ros.org) web site.
66

7-
Dependencies for Build:
8-
* `sudo apt install python3-pip`
9-
* `pip3 install sphinx==3.5.0 breathe==4.28.0 sphinx_rtd_theme sphinxcontrib-plantuml jinja2==3.0.3`
7+
Dependencies for Build:
8+
9+
``` bash
10+
sudo apt install python3-pip
11+
pip3 install -r requirements.txt
12+
```
1013

1114
Build the docs locally with `make html` and you'll find the built docs entry point in `_build/html/index.html`.
1215

13-
Any images, diagrams, or videos are subject to their own copyrights, trademarks, and licenses.
16+
Any images, diagrams, or videos are subject to their own copyrights, trademarks, and licenses.

0 commit comments

Comments
 (0)