diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 00000000000..3f30677cd2c
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..2393435f7a2
--- /dev/null
+++ 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
deleted file mode 100644
index c17f235418b..00000000000
--- a/.travis.yml
+++ /dev/null
@@ -1,18 +0,0 @@
-language: python
-python: 3.6
-dist: xenial
-os: linux
-install:
- - pip3 install doc8 sphinx
- - pip3 install git+https://github.com/osrf/sphinx-tabs
-
-script:
- - make html 2> stderr.log
- - cat stderr.log
- - doc8 --ignore D001 --ignore-path build --ignore-path source/Tutorials/Actions
- # ignore D000 in action tutorials to allow for :linenos:
- - doc8 --ignore D000 --ignore D001 --ignore-path build source/Tutorials/Actions
- # fail the build for any stderr output
- - if [ -s "stderr.log" ]; then false; fi
-notifications:
- email: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index f6dead8ad37..00000000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Contribute
-
-The source files for all the ROS 2 documentation are under the /source directory. The sources are in [ReStructuredText](http://docutils.sourceforge.net/rst.html) format (.rst).
-
-
-## Building documentation locally
-
-Please refer to the [README.md](README.md) file in this repository for instructions on how to build the documentation locally.
-
-
-## Submit a Pull Request
-
-If you are a GitHub user, the most effective way to contribute is to submit a pull request with the changes you want to suggest.
-
-
-## Raise a GitHub Issue
-
-If you don't feel comfortable creating a pull request or you want to make a general suggestion or start a discussion about the documentation, you can create a GitHub issue on this repository.
-
-
-# Contributing to ROS 2
-
-To contribute to the ROS 2 source code project please refer to the [ROS 2 contributing guidelines](https://index.ros.org/doc/ros2/Contributing/).
diff --git a/Makefile b/Makefile
index f983afa722d..21711208f1d 100644
--- 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 "" > build/html/index.html
+
+.PHONY: help Makefile multiversion
%: Makefile
@$(BUILD) -M $@ "$(SOURCE)" "$(OUT)" $(OPTS)
diff --git a/README.md b/README.md
index 722ef349082..6f4bbf6cc8f 100644
--- 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
index fed9b8ad373..d16a7e5b33d 100644
--- 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,18 +73,18 @@
# 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 ----------------------------------------------
@@ -85,7 +92,34 @@
# 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 = """
-
+