diff --git a/.circleci/config.yml b/.circleci/config.yml
index 5c6c2a06aad8570f5ff5771c65e72e0ed534142e..e08009f2f3c899e3aa5357aace05f7a47ac27bd4 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -285,7 +285,10 @@ references:
command: |
cd src/navigation2/sphinx_doc
make html
-
+ store_docs: &store_docs
+ store_artifacts:
+ path: /opt/overlay_ws/src/navigation2/sphinx_doc/_build/html
+ destination: html
commands:
<<: *common_commands
checkout_source:
@@ -335,6 +338,7 @@ commands:
description: "Build docs"
steps:
- *make_docs
+ - *store_docs
executors:
debug_exec:
diff --git a/sphinx_doc/getting_started/index.rst b/sphinx_doc/getting_started/index.rst
index 8779a82d05646212e3e5efb705c957c9d53d1142..9b72a8b7a96c51c42d3a9920123fdafa3f4b98aa 100644
--- a/sphinx_doc/getting_started/index.rst
+++ b/sphinx_doc/getting_started/index.rst
@@ -3,5 +3,129 @@
Getting Started
###############
-This website is under construction. Please visit the `project repo`_ in the
-meantime.
+This document will take you through the process of installing the |PN| binaries
+and navigating a simulated Turtlebot 3 in the Gazebo simulator. We'll use the
+|Distro| version of ROS 2, since it is the latest stable version at the time
+this was written. The instructions are written primarily for Ubuntu 18, using
+the standard installation options.
+
+.. note::
+
+ See the :ref:`howtos` for other situations such as building from source or
+ working with other types of robots.
+
+.. warning::
+
+ This is a simplified version of the Turtlebot 3 instructions. We highly
+ recommend you follow the `official Turtlebot 3 manual`_ if you intend to
+ continue working with this robot beyond the minimal example provided here.
+
+Installation
+************
+
+1. Install the `ROS 2 binary packages`_ as described in the official docs
+2. Install the |PN| packages using your operating system's package manager. For
+ Ubuntu 18, do this:
+
+ .. code-block:: bash
+
+ sudo apt install ros2-dashing-navigation2
+ sudo apt install ros2-dashing-nav2-bringup
+
+3. Install the Turtlebot 3 packages. Again, for Ubuntu 18, it looks like this:
+
+ .. code-block:: bash
+
+ sudo apt install ros2-dashing-turtlebot3*
+
+Running the Example
+*******************
+
+1. Start a terminal in your GUI
+2. Set key environment variables. Here's how to do it in Ubuntu.
+
+ .. code-block:: bash
+
+ source /opt/ros/dashing/setup.bash
+ export TURTLEBOT3_MODEL=waffle
+ export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:/opt/ros/dashing/share/turtlebot3_gazebo/models
+
+3. In the same terminal, run
+
+ .. code-block:: bash
+
+ ros2 launch nav2_bringup nav2_tb3_simulation_launch.py
+
+
+ If everything has started correctly, you will see the RViz and Gazebo GUIs like
+ this.
+
+ .. figure:: /images/rviz/rviz-not-started.png
+ :scale: 50%
+ :alt: Initial appearance of RViz before hitting startup button
+
+ Initial appearance of RViz before hitting startup button. Nothing is
+ displayed at this point because |PN| is still in the unconfigured state
+
+ .. figure:: /images/gazebo/gazebo_turtlebot1.png
+ :scale: 50%
+ :alt: Initial appearance of Gazebo with Turtlebot 3 world
+
+ Initial appearance of Gazebo with Turtlebot 3 world
+
+4. Click the "Startup" button in the bottom left corner of RViz. This will
+ cause |PN| to change to the Active lifecycle state. It should
+ change appearance to show the map.
+
+ .. figure:: /images/rviz/rviz_initial.png
+ :scale: 50%
+ :alt: Initial appearance of RViz transitioning to the Active state
+
+ Initial appearance of RViz transitioning to the Active state
+
+Navigating
+**********
+
+1. After starting, the robot initially has no idea where it is. By default,
+ |PN| waits for you to give it an approximate starting position. Take a look
+ at where the robot is in the Gazebo world, and find that spot on the map. Set
+ the initial pose by clicking the "2D Pose Estimate" button in RViz, and then
+ down clicking on the map in that location. You set the orientation by dragging
+ forward from the down click.
+
+ If you are using the defaults so far, it should look like this.
+
+ .. figure:: /images/rviz/rviz-set-initial-pose.png
+ :scale: 50%
+ :alt: Approximate starting location of Turtlebot
+
+ Approximate starting location of Turtlebot
+
+ If you don't get the location exactly right, that's fine. |PN| will refine
+ the position as it navigates. You can also, click the "2D Pose
+ Estimate" button and try again, if you prefer.
+
+ Once you've set the initial pose, the trasform tree will be complete and
+ |PN| is fully active and ready to go.
+
+ .. figure:: /images/rviz/navstack-ready.png
+ :scale: 50%
+ :alt: |PN| is ready. Transforms and Costmap show in RViz.
+
+ |PN| is ready. Transforms and Costmap show in RViz.
+
+2. Click the "Navigaton2 Goal" button and choose a destination.
+
+ .. figure:: /images/rviz/navigate-to-pose.png
+ :scale: 50%
+ :alt: Setting the goal pose in RViz.
+
+ Setting the goal pose in RViz.
+
+ Watch the robot go!
+
+ .. figure:: /images/rviz/navigating.png
+ :scale: 50%
+ :alt: Turtlebot on its way to the goal.
+
+ Turtlebot on its way to the goal.
diff --git a/sphinx_doc/how_it_works/index.rst b/sphinx_doc/how_it_works/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..553b8adfc95d8f946416d905dee5b39fea26b1f8
--- /dev/null
+++ b/sphinx_doc/how_it_works/index.rst
@@ -0,0 +1,7 @@
+.. _how_it_works:
+
+How It Works
+############
+
+This website is under construction. Please visit the `project repo`_ in the
+meantime.
diff --git a/sphinx_doc/images/gazebo/gazebo_turtlebot1.png b/sphinx_doc/images/gazebo/gazebo_turtlebot1.png
new file mode 100644
index 0000000000000000000000000000000000000000..b5776b16f4079886429c01ecf31b5009f3d9be7c
Binary files /dev/null and b/sphinx_doc/images/gazebo/gazebo_turtlebot1.png differ
diff --git a/sphinx_doc/images/rviz/navigate-to-pose.png b/sphinx_doc/images/rviz/navigate-to-pose.png
new file mode 100644
index 0000000000000000000000000000000000000000..0634a46c8c1f5f954d86f97dbfe76e51b58f88a9
Binary files /dev/null and b/sphinx_doc/images/rviz/navigate-to-pose.png differ
diff --git a/sphinx_doc/images/rviz/navigating.png b/sphinx_doc/images/rviz/navigating.png
new file mode 100644
index 0000000000000000000000000000000000000000..3e84ce8098d024b57de12869886a76942131df9f
Binary files /dev/null and b/sphinx_doc/images/rviz/navigating.png differ
diff --git a/sphinx_doc/images/rviz/navstack-ready.png b/sphinx_doc/images/rviz/navstack-ready.png
new file mode 100644
index 0000000000000000000000000000000000000000..43e89ea6caffa881d8aed6f79951f86fc8e292cb
Binary files /dev/null and b/sphinx_doc/images/rviz/navstack-ready.png differ
diff --git a/sphinx_doc/images/rviz/rviz-not-started.png b/sphinx_doc/images/rviz/rviz-not-started.png
new file mode 100644
index 0000000000000000000000000000000000000000..733471141b68b902df8250104f5c2132fd0726ed
Binary files /dev/null and b/sphinx_doc/images/rviz/rviz-not-started.png differ
diff --git a/sphinx_doc/images/rviz/rviz-set-initial-pose.png b/sphinx_doc/images/rviz/rviz-set-initial-pose.png
new file mode 100644
index 0000000000000000000000000000000000000000..c732e2ecf537ad84a5d0e4b1c79bd2dba0b2d3bb
Binary files /dev/null and b/sphinx_doc/images/rviz/rviz-set-initial-pose.png differ
diff --git a/sphinx_doc/images/rviz/rviz_initial.png b/sphinx_doc/images/rviz/rviz_initial.png
new file mode 100644
index 0000000000000000000000000000000000000000..5a1a4e505b1111f8df03526bf722e1b26bfdf668
Binary files /dev/null and b/sphinx_doc/images/rviz/rviz_initial.png differ
diff --git a/sphinx_doc/index.rst b/sphinx_doc/index.rst
index 404bddfedaedaa56498021ed312e1f5f9e25432b..7b9d996c864812e14581d5e404ba3bbf7721477e 100644
--- a/sphinx_doc/index.rst
+++ b/sphinx_doc/index.rst
@@ -1,10 +1,36 @@
.. _documentation_home:
+*****
|LPN|
-#####
+*****
-This website is under construction. Please visit the `project repo`_ in the
-meantime.
+.. raw:: html
+
+ <div style="position: relative; padding-bottom: 0%; overflow: hidden; max-width: 100%; height: auto;">
+ <iframe width="560" height="315" src="https://www.youtube.com/embed/ZeCds7Sv-5Q" frameborder="0" allowfullscreen></iframe>
+ </div>
+
+Overview
+########
+
+The |PN| project is a set of ROS2 components that help you build a robot that
+can drive around.
+
+It has tools to:
+
+- load and store maps
+- localize the robot on the map
+- plan a path from A to B around obstacles
+- control the robot as it follows the path and avoid any obstacles along the way
+- convert sensor data into a costmap representation of the world
+- build complicated robot behaviors using behavior trees
+
+These all work seemlessly together, so that, with a bit of customization for your
+robot, you can just give it a destination and off it go.
+
+Here you will find documentation on how to install and use |PN| with a Turtlebot
+3, as well as how to customize it for other robots, tune the behavior for better
+performance, as well as customize the internals for advanced results.
Sections
********
@@ -13,6 +39,7 @@ Sections
:maxdepth: 1
getting_started/index.rst
+ how_it_works/index.rst
howtos/index.rst
release_notes.rst
contribute/index.rst
diff --git a/sphinx_doc/substitutions.txt b/sphinx_doc/substitutions.txt
index c534aab4c919c4dc999bc5ac461392f1dc811206..cfd56b99a7dcd57a789b1d29762752816f73207f 100644
--- a/sphinx_doc/substitutions.txt
+++ b/sphinx_doc/substitutions.txt
@@ -15,6 +15,14 @@
.. |PP| replace:: https://github.com/ros-planning/navigation2/blob/master
+.. |Distro| replace:: Dashing
+
+.. |distro| replace:: dashing
+
+.. _`ROS 2 binary packages`: https://index.ros.org/doc/ros2/Installation/Dashing/#binary-packages
+
+.. _`official Turtlebot 3 manual`: http://emanual.robotis.com/docs/en/platform/turtlebot3/ros2/#ros2
+
.. These are replacement strings for non-ASCII characters used within the project
using the same name as the html entity names (e.g., ©) for that character