IkerLuengo · IkerLuengo · Dec 3, 2020 · Dec 14, 2020 · Dec 14, 2020 · Dec 17, 2020
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -0,0 +1,22 @@
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.8
+
+      - name: Install dependencies with pip
+        run: |
+          pip install --no-warn-script-location --user --upgrade -r requirements.txt
+          pip install doc8
+
+      - run: make html
+      - run: doc8 --ignore D001 --ignore-path build
diff --git a/.mergify.yml b/.mergify.yml
@@ -0,0 +1,38 @@
+pull_request_rules:
+  - name: automatic backport of common pages
+    conditions:
+      - base=rolling
+      - "files~=Governance|Contact|index|Marketing|ROSCon-Content|Roadmap|Releases|Feature-Ideas"
+    actions:
+      backport:
+        branches:
+          - foxy
+          - dashing
+
+  - name: backport at reviewers discretion
+    conditions:
+      - base=rolling
+      - "label=backport-all"
+    actions:
+      backport:
+        branches:
+          - foxy
+          - dashing
+
+  - name: backport to foxy at reviewers discretion
+    conditions:
+      - base=rolling
+      - "label=backport-foxy"
+    actions:
+      backport:
+        branches:
+          - foxy
+
+  - name: backport to dashing at reviewers discretion
+    conditions:
+      - base=rolling
+      - "label=backport-dashing"
+    actions:
+      backport:
+        branches:
+          - dashing
diff --git a/.travis.yml b/.travis.yml
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/Makefile b/Makefile
@@ -7,7 +7,12 @@ OPTS       =-c .
 
 help:
 	@$(BUILD) -M help "$(SOURCE)" "$(OUT)" $(OPTS)
+	@echo "  multiversion to build documentation for all branches"
 
-.PHONY: help Makefile
+multiversion: Makefile
+	sphinx-multiversion $(OPTS) "$(SOURCE)" build/html
+	@echo "<html><head><meta http-equiv=\"refresh\" content=\"0; url='foxy/index.html'\" /></head></html>" > build/html/index.html
+
+.PHONY: help Makefile multiversion
 %: Makefile
 	@$(BUILD) -M $@ "$(SOURCE)" "$(OUT)" $(OPTS)
diff --git a/README.md b/README.md
@@ -1,35 +1,47 @@
-ROS Documentation
-=================
+# ROS 2 Documentation
 
+This repository contains the sources for the ROS 2 documentation that is hosted at [https://docs.ros.org/en](https://docs.ros.org/en).
+The sources from this repository are built and uploaded to the site nightly by a [Jenkins job](https://build.ros.org/job/doc_ros2doc).
 
-This is the ROS 2 documentation site.
+## Contributing to the documentation
 
+Contributions to this site are most welcome.
+Please be sure to read the below sections carefully before contributing.
 
-## Project structure
+The site is built using [Sphinx](https://www.sphinx-doc.org/en/master/), and more particularly using [Sphinx multiversion](https://holzhaus.github.io/sphinx-multiversion/master/index.html).
 
-Under /source are the source files for the site.
-In the root directory are the files required to locally build the site for testing.
+### Installing prerequisites
 
+```
+pip3 install --user --upgrade -r requirements.txt
+```
 
-## Build the site locally
+### Branch structure
 
-### Prerequisites
+This repository is setup with one branch per ROS 2 distribution to handle differences between the distributions.
+If a change is common to all ROS 2 distributions, it should be made to the `rolling` branch (and then will be backported as appropriate).
+If a change is specific to a particular ROS 2 distribution, it should be made to the respective branch.
 
-You must have sphinx and the sphinx-tabs extension installed, preferably using pip:
+### Source structure
 
-```
-pip3 install sphinx sphinx-tabs
-```
+The source files for the site are all located under the `source` subdirectory.
+Templates for various sphinx plugins are located under `source/_templates`.
+The root directory contains configuration and files required to locally build the site for testing.
 
-For other distributions please refer to http://www.sphinx-doc.org/en/master/usage/installation.html
+### Building the site
 
+To build the site for just this branch, type `make html` at the top-level of the repository.
+This is the recommended way to test out local changes.
 
-### Build the site
+To build the site for all branches, type `make multiversion` from the `rolling` branch.
+This has two drawbacks:
 
-To build the site just execute:
+1. The multiversion plugin doesn't understand how to do incremental builds, so it always rebuilds everything.  This can be slow.
+1. When typing `make multiversion`, it will always check out exactly the branches listed in the `conf.py` file.  That means that local changes will not be shown.
 
-```
-make html
-```
+To show local changes in the multiversion output, you must first commit the changes to a local branch.
+Then you must edit the [conf.py](./conf.py) file and change the `smv_branch_whitelist` variable to point to your branch.
+
+## Contributing to ROS 2
 
-The site will be generated in the build/html directory. The main page is index.html
+To contribute to the ROS 2 source code project please refer to the [ROS 2 contributing guidelines](https://docs.ros.org/en/rolling/Contributing).
diff --git a/conf.py b/conf.py
@@ -16,10 +16,17 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
+
 import itertools
+import os
+import sys
+import time
+
 from docutils.parsers.rst import Directive
 
+sys.path.append(os.path.abspath('./sphinx-multiversion'))
+
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -33,9 +40,9 @@
 suppress_warnings = ['image.nonlocal_uri']
 
 # General information about the project.
-project = u'ros2 documentation'
-copyright = u'2018, Open Robotics'
-author = u'Open Robotics'
+project = 'ROS 2 documentation'
+author = 'Open Robotics'
+copyright = '{}, {}'.format(time.strftime('%Y'), author)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -66,26 +73,53 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-extensions = ['sphinx.ext.intersphinx', 'sphinx_tabs.tabs']
+extensions = ['sphinx.ext.intersphinx', 'sphinx_tabs.tabs', 'sphinx_multiversion', 'sphinx_rtd_theme']
 
 # Intersphinx mapping
 
 intersphinx_mapping = {
-    'catkin_pkg':    ('http://docs.ros.org/independent/api/catkin_pkg/html', None),
-    'jenkins_tools': ('http://docs.ros.org/independent/api/jenkins_tools/html', None),
-    'rosdep':        ('http://docs.ros.org/independent/api/rosdep/html', None),
-    'rosdistro':     ('http://docs.ros.org/independent/api/rosdistro/html', None),
-    'rosinstall':    ('http://docs.ros.org/independent/api/rosinstall/html', None),
-    'rospkg':        ('http://docs.ros.org/independent/api/rospkg/html', None),
-    'vcstools':      ('http://docs.ros.org/independent/api/vcstools/html', None)
+    'catkin_pkg':    ('http://docs.ros.org/en/independent/api/catkin_pkg/html', None),
+    'jenkins_tools': ('http://docs.ros.org/en/independent/api/jenkins_tools/html', None),
+    'rosdep':        ('http://docs.ros.org/en/independent/api/rosdep/html', None),
+    'rosdistro':     ('http://docs.ros.org/en/independent/api/rosdistro/html', None),
+    'rosinstall':    ('http://docs.ros.org/en/independent/api/rosinstall/html', None),
+    'rospkg':        ('http://docs.ros.org/en/independent/api/rospkg/html', None),
+    'vcstools':      ('http://docs.ros.org/en/independent/api/vcstools/html', None)
 }
 
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'navigation_depth': -1,
+}
+
+html_context = {
+    'display_github': True,
+    'github_user': 'ros2',
+    'github_repo': 'ros2_documentation',
+    'github_version': 'rolling/source/',  # Will be overridden when building multiversion
+}
+
+templates_path = [
+    "source/_templates",
+]
+
+# smv_tag_whitelist = None
+
+smv_branch_whitelist = r'^(rolling|foxy|eloquent|dashing|crystal)$'
+
+
+smv_released_pattern = r'^refs/(heads|remotes/[^/]+)/(foxy|eloquent|dashing|crystal).*$'
+smv_remote_whitelist = r'^(origin)$'
+smv_latest_version = 'foxy'
+
+
 
 html_favicon = 'favicon.ico'
 
@@ -102,6 +136,7 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ros2_docsdoc'
 
+html_baseurl = 'https://docs.ros.org/en'
 
 class RedirectFrom(Directive):
 
@@ -120,8 +155,9 @@ def generate(cls, app):
         from sphinx.builders.html import StandaloneHTMLBuilder
         if not isinstance(app.builder, StandaloneHTMLBuilder):
             return
+
         redirect_html_fragment = """
-            <link rel="canonical" href="{url}" />
+            <link rel="canonical" href="{base_url}/{url}" />
             <meta http-equiv="refresh" content="0; url={url}" />
             <script>
                 window.location.href = '{url}';
@@ -169,6 +205,7 @@ def generate(cls, app):
                     ),
                     'title': os.path.basename(redirect_url),
                     'metatags': redirect_html_fragment.format(
+                        base_url=app.config.html_baseurl,
                         url=app.builder.get_relative_uri(
                             redirect_url, canonical_url
                         )
@@ -203,9 +240,21 @@ def _missing_reference(app, env, node, contnode):
                 return newnode
     return _missing_reference
 
+def smv_rewrite_baseurl(app, config):
+    # When using Sphinx multiversion, there is no way at initial configuration time
+    # to determine the distribution we are currently targeting (conf.py is read before
+    # external defines are setup, and environment variables aren't passed through to
+    # conf.py).  Instead, hook into the 'config-inited' event which is late enough
+    # to rewrite the html_baseurl with the current version.
+    if app.config.smv_current_version != '':
+        app.config.html_baseurl = app.config.html_baseurl + '/' + app.config.smv_current_version
+        app.config.project = 'ROS 2 Documentation: ' + app.config.smv_current_version.title()
+
+def github_link_rewrite_branch(app, pagename, templatename, context, doctree):
+    if app.config.smv_current_version != '':
+        context['github_version'] = app.config.smv_current_version + '/source/'
 
 def setup(app):
+    app.connect('config-inited', smv_rewrite_baseurl)
+    app.connect('html-page-context', github_link_rewrite_branch)
     RedirectFrom.register(app)
-    app.connect('missing-reference', make_router(
-        'Installation', 'Installation/Eloquent'
-    ))
diff --git a/docker/image/Dockerfile b/docker/image/Dockerfile
@@ -0,0 +1,27 @@
+# This dockerfile is expecting to be run with the following build command
+# (from the root of the git repository):
+#
+# docker build -f docker/image/Dockerfile .
+
+FROM ubuntu:focal
+
+ARG user=rosindex
+ARG uid=1000
+
+ENV DEBIAN_FRONTEND noninteractive
+
+RUN apt-get update && \
+    apt-get install --no-install-recommends -y \
+        git-all \
+        make \
+        python3-pip && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN useradd -u $uid -m $user
+ENV HOME=/home/$user
+ENV PATH=/home/$user/.local/bin:$PATH
+WORKDIR /tmp/doc_repository
+
+USER $user
+
+CMD pip3 install --no-warn-script-location --user --upgrade -r requirements.txt && make multiversion
diff --git a/global_substitutions.txt b/global_substitutions.txt
@@ -0,0 +1,17 @@
+.. |ament packages| replace:: :term:`ament packages <ament package>`
+
+.. |API| replace:: :term:`API`
+.. |APIs| replace:: :term:`APIs <API>`
+
+.. |client library| replace:: :term:`client library <client_library>`
+.. |client libraries| replace:: :term:`client libraries <client_library>`
+
+.. |GitHub| replace:: GitHub
+.. _GitHub: https://github.com/
+
+.. |package| replace:: :term:`package`
+.. |packages| replace:: :term:`packages <package>`
+
+.. |REPs| replace:: :term:`REPs <REP>`
+
+.. |rclcpp| replace:: :term:`rclcpp`
diff --git a/requirements.txt b/requirements.txt
@@ -1,3 +1,5 @@
 pip
-Sphinx
+sphinx
 sphinx-tabs
+sphinx-multiversion
+sphinx-rtd-theme