Add docs for Dev Containers

.circleci/config.yml

@@ -3,25 +3,26 @@ 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:
@@ -30,7 +31,6 @@ references:
   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.