Add docs for Dev Containers (#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

.circleci/config.yml

@@ -3,34 +3,34 @@ version: 2.1
 references:
   on_checkout: &on_checkout
     checkout:
-      path: nav2_docs
+      path: .
   setup_doc_dependencies: &setup_doc_dependencies
     run:
       name: Install Doc Dependencies
       command: |
         export DEBIAN_FRONTEND=noninteractive
         apt update
-        apt install make -y
-        apt install doxygen -y
-        apt install graphviz -y
-        apt install ttf-dejavu -y
-        apt install openjdk-8-jre -y
-        apt install bash git openssh-server -y
-        apt install python3-pip python3 -y
-        pip3 install sphinx==3.5.0 docutils==0.14 sphinx_rtd_theme breathe==4.28.0 sphinxcontrib-plantuml jinja2==3.0.3
+        apt install -y \
+          doxygen \
+          git \
+          graphviz \
+          make \
+          openjdk-8-jre \
+          openssh-server \
+          python3-pip \
+          ttf-dejavu
+        pip3 install -r requirements.txt
   make_docs: &make_docs
     run:
       command: |
-        cd nav2_docs
         make html
   store_docs: &store_docs
     store_artifacts:
-        path: nav2_docs/_build/html
+        path: _build/html
         destination: html
   publish_docs: &publish_docs
     run:
       command: |
-        cd nav2_docs
         make publish
   install_deployment_key: &install_deployment_key
     add_ssh_keys:
@@ -56,27 +56,27 @@ executors:
   docs_exec:
     docker:
       - image: ubuntu:focal
-    working_directory: /
+    working_directory: /nav2_docs
 
 jobs:
   docs_build:
     executor: docs_exec
     steps:
-      - install_doc_dependencies
       - *on_checkout
+      - install_doc_dependencies
       - build_docs
       - persist_to_workspace:
-          root: nav2_docs
+          root: .
           paths:
             - _build 
   docs_publish:
     executor: docs_exec
     steps:
-      - install_doc_dependencies
       - *on_checkout
+      - install_doc_dependencies
       - *install_deployment_key
       - attach_workspace:
-          at: nav2_docs
+          at: .
       - publish_docs_to_gh_pages_branch
 
 workflows:

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+    "name": "Nav2 Docs",
+    "build": {
+        "dockerfile": "../Dockerfile",
+        "context": ".."
+    },
+    "workspaceMount": "source=${localWorkspaceFolder},target=/docs,type=bind",
+    "workspaceFolder": "/docs",
+    "onCreateCommand": ".devcontainer/on-create-command.sh",
+    "updateContentCommand": ".devcontainer/update-content-command.sh",
+    "customizations": {
+        "vscode": {
+            "settings": {},
+            "extensions": [
+                "eamodio.gitlens",
+                "esbenp.prettier-vscode",
+                "GitHub.copilot",
+                "streetsidesoftware.code-spell-checker"
+            ]
+        }
+    }
+}

.devcontainer/on-create-command.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# Immediately catch all errors
+set -eo pipefail
+
+# Uncomment for debugging
+# set -x
+# env
+
+git config --global --add safe.directory "*"
+
+.devcontainer/update-content-command.sh

.devcontainer/update-content-command.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Immediately catch all errors
+set -eo pipefail
+
+# Uncomment for debugging
+# set -x
+# env
+
+# make clean
+# make html

.dockerignore

@@ -0,0 +1,13 @@
+################################################################################
+# Repo
+
+.circleci/
+.devcontainer/
+.dockerignore
+.git/
+.github/
+.gitignore
+.vscode/
+**.Dockerfile
+**Dockerfile
+_build/

.vscode/tasks.json

@@ -0,0 +1,35 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build",
+            "icon": {
+                "id": "gear"
+            },
+            "type": "shell",
+            "command": "make html",
+            "isBackground": false,
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+              }
+        },
+        {
+            "label": "Autobuild",
+            "icon": {
+                "id": "debug-start"
+            },
+            "type": "shell",
+            "command": "make autobuild",
+            "isBackground": true,
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": false
+              }
+        }
+    ]
+}

2021summerOfCode/Summer_2021_Student_Program.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _summer_2021_student_program:
 
 

2021summerOfCode/projects/create_configuration_assistant.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _create_moveit_analog:
 
 1. Create a Configuration Assistant (Analog to MoveIt)

2021summerOfCode/projects/create_plugins.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _create_plugins:
 
 

2021summerOfCode/projects/grid_maps.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _grid_maps:
 
 

2021summerOfCode/projects/localization.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _localization:
 
 

2021summerOfCode/projects/navigation_rebranding.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _rebranding:
 
 

Dockerfile

@@ -0,0 +1,16 @@
+FROM ubuntu:focal
+
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt update && \
+    apt install -y \
+        doxygen \
+        git \
+        graphviz \
+        make \
+        openjdk-8-jre \
+        openssh-server \
+        python3-pip \
+        ttf-dejavu
+
+COPY requirements.txt ./
+RUN pip3 install -r requirements.txt

Makefile

@@ -8,7 +8,7 @@ else
 endif
 
 # You can set these variables from the command line.
-SPHINXOPTS    ?= -q
+SPHINXOPTS    ?=
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = "Nav2 Documentation"
 SOURCEDIR     = .
@@ -35,6 +35,11 @@ help:
 html:
 	$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O)
 
+# Autobuild the docs on changes
+
+autobuild:
+	sphinx-autobuild -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS)
+
 # Remove generated content (Sphinx and doxygen)
 
 clean:

README.md

@@ -4,10 +4,13 @@ https://navigation.ros.org/
 This folder holds the source and configuration files used to generate the
 [Navigation2 documentation](https://navigation.ros.org) web site.
 
-Dependencies for Build: 
-* `sudo apt install python3-pip`
-* `pip3 install sphinx==3.5.0 breathe==4.28.0 sphinx_rtd_theme sphinxcontrib-plantuml jinja2==3.0.3`
+Dependencies for Build:
+
+``` bash
+sudo apt install python3-pip
+pip3 install -r requirements.txt
+```
 
 Build the docs locally with `make html` and you'll find the built docs entry point in `_build/html/index.html`.
 
-Any images, diagrams, or videos are subject to their own copyrights, trademarks, and licenses. 
+Any images, diagrams, or videos are subject to their own copyrights, trademarks, and licenses.