Cleaning up the overview page (ros2#434)

* Cleaning up the overview page Signed-off-by: maryaB-osr <[email protected]> * update reference syntax Signed-off-by: maryaB-osr <[email protected]> * logically reorder main pages Signed-off-by: maryaB-osr <[email protected]> * added related projects section back Signed-off-by: maryaB-osr <[email protected]>
RavingRoss · Nov 21, 2019 · 4273cc6 · 4273cc6
1 parent d2e7930
commit 4273cc6
Show file tree

Hide file tree

Showing 14 changed files with 115 additions and 115 deletions.
diff --git a/source/About.rst b/source/About.rst
diff --git a/source/Concepts.rst b/source/Concepts.rst
@@ -1,3 +1,4 @@
+.. _ConceptsHome:
 
 Concepts
 ========

diff --git a/source/Contact.rst b/source/Contact.rst
@@ -1,3 +1,4 @@
+.. _Help:
 
 Contact us
 ==========
@@ -33,4 +34,4 @@ When filing an issue, please make sure to:
 * In case of a bug consider providing a `short, self contained, correct (compilable), example <http:https://sscce.org/>`__.
 
 Pull requests are welcome for any of `the ros2 repositories <https://github.com/ros2>`__ to suggest specific code changes!
-See `Contributing <Contributing>` for more details on how to contribute.
+See :ref:`Contributing <Contributing>` for more details on how to contribute.
diff --git a/source/Contributing.rst b/source/Contributing.rst
@@ -1,3 +1,4 @@
+.. _Contributing:
 
 Contributing
 ============

diff --git a/source/Features.rst b/source/Features.rst
@@ -1,10 +1,11 @@
+.. _Features:
 
 Features Status
 ===============
 
 The features listed below are available in the current ROS 2 release.
 Unless otherwise specified, the features are available for all supported platforms (Ubuntu 18.04, OS X 10.12.x, Windows 10), DDS implementations (eProsima Fast RTPS, RTI Connext and ADLINK Opensplice) and programming language client libraries (C++ and Python).
-For planned future development, see the `Roadmap <Roadmap>`.
+For planned future development, see the :ref:`Roadmap <Roadmap>`.
 
 .. list-table::
  :header-rows: 1

diff --git a/source/Governance.rst b/source/Governance.rst
@@ -1,3 +1,4 @@
+.. _Governance:
 
 Project Governance
 ==================

diff --git a/source/Marketing.rst b/source/Marketing.rst
@@ -1,3 +1,4 @@
+.. _Marketing:
 
 Marketing Materials
 ===================
@@ -15,4 +16,3 @@ Available formats:
 * :download:`A4 (for print) <Marketing/ros2-brochure-a4-print.pdf>`
 * :download:`US Letter (for web/email) <Marketing/ros2-brochure-ltr-web.pdf>`
 * :download:`US Letter (for print) <Marketing/ros2-brochure-ltr-print.pdf>`
-
diff --git a/source/ROSCon-Content.rst b/source/ROSCon-Content.rst
@@ -0,0 +1,43 @@
+.. _ROSCon:
+
+ROSCon content
+==============
+
+The following `ROSCon <http:https://roscon.ros.org>`__ talks have been given on ROS 2 and provide information about the workings of ROS 2 and various demos:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Title
+ - Type
+ - Links
+ * - Hands-on ROS 2: A Walkthrough
+ - ROSCon 2018 presentation
+ - `slides <https://roscon.ros.org/2018/presentations/ROSCon2018_ROS2HandsOn.pdf>`__ / `video <https://vimeo.com/292693129>`__
+ * - Launch for ROS 2
+ - ROSCon 2018 presentation
+ - `slides <https://roscon.ros.org/2018/presentations/ROSCon2018_launch.pdf>`__ / `video <https://vimeo.com/292699162>`__
+ * - The ROS 2 vision for advancing the future of robotics development
+ - ROSCon 2017 presentation
+ - `slides <https://roscon.ros.org/2017/presentations/ROSCon%202017%20ROS2%20Vision.pdf>`__ / `video <https://vimeo.com/236161417>`__
+ * - ROS 2 Update - summary of alpha releases, architectural overview
+ - ROSCon 2016 presentation
+ - `slides <http:https://roscon.ros.org/2016/presentations/ROSCon%202016%20-%20ROS%202%20Update.pdf>`__ / `video <https://vimeo.com/187696091>`__
+ * - Evaluating the resilience of ROS2 communication layer
+ - ROSCon 2016 presentation
+ - `slides <http:https://roscon.ros.org/2016/presentations/rafal.kozik-ros2evaluation.pdf>`__ / `video <https://vimeo.com/187705229>`__
+ * - State of ROS 2 - demos and the technology behind
+ - ROSCon 2015 presentation
+ - `slides <http:https://roscon.ros.org/2015/presentations/state-of-ros2.pdf>`__ / `video <https://vimeo.com/142151734>`__
+ * - ROS 2 on "small" embedded systems
+ - ROSCon 2015 presentation
+ - `slides <http:https://roscon.ros.org/2015/presentations/ros2_on_small_embedded_systems.pdf>`__ / `video <https://vimeo.com/142150576>`__
+ * - Real-time control in ROS and ROS 2
+ - ROSCon 2015 presentation
+ - `slides <http:https://roscon.ros.org/2015/presentations/RealtimeROS2.pdf>`__ / `video <https://vimeo.com/142621778>`__
+ * - Why you want to use ROS 2
+ - ROSCon 2014 presentation
+ - `slides <http:https://www.osrfoundation.org/wordpress2/wp-content/uploads/2015/04/ROSCON-2014-Why-you-want-to-use-ROS-2.pdf>`__ / `video <https://vimeo.com/107531013>`__
+ * - Next-generation ROS: Building on DDS
+ - ROSCon 2014 presentation
+ - `slides <http:https://roscon.ros.org/2014/wp-content/uploads/2014/07/ROSCON-2014-Next-Generation-of-ROS-on-top-of-DDS.pdf>`__ / `video <https://vimeo.com/106992622>`__
diff --git a/source/Related-Projects/Intel-ROS2-Projects.rst b/source/Related-Projects/Intel-ROS2-Projects.rst
@@ -1,6 +1,6 @@
 .. redirect-from::
 
-  Intel-ROS2-Projects
+ Intel-ROS2-Projects
 
 Intel ROS2 Projects
 ===================
@@ -12,7 +12,7 @@ Key Projects
 
 We are working on below ROS2 projects and publish source code through https://github.com/intel/ or ROS2 github repo gradually.
 
-*  `ROS2 OpenVINO <https://github.com/intel/ros2_openvino_toolkit>`__: ROS2 package for Intel® Visual Inference and Neural Network Optimization Toolkit to develop multiplatform computer vision solutions.
+* `ROS2 OpenVINO <https://github.com/intel/ros2_openvino_toolkit>`__: ROS2 package for Intel® Visual Inference and Neural Network Optimization Toolkit to develop multiplatform computer vision solutions.
 * `ROS2 RealSense Camera <https://github.com/intel/ros2_intel_realsense>`__: ROS2 package for Intel® RealSense™ D400 serial cameras
 * `ROS2 Movidius NCS <https://github.com/intel/ros2_intel_movidius_ncs>`__: ROS2 package for object detection with Intel® Movidius™ Neural Computing Stick (NCS).
 * `ROS2 Object Messages <https://github.com/intel/ros2_object_msgs>`__: ROS2 messages for object.

diff --git a/source/Releases.rst b/source/Releases.rst
@@ -1,3 +1,4 @@
+.. _Releases:
 
 Distributions
 =============
@@ -88,7 +89,7 @@ For the supported platforms and versions of common dependencies and other consid
 Future Distributions
 --------------------
 
-For details on upcoming features see the `roadmap <Roadmap>`.
+For details on upcoming features see the :ref:`roadmap <Roadmap>`.
 
 Currently there is a new ROS 2 distribution roughly every 6 months.
 The following information are best estimates and are subject to change.

diff --git a/source/Roadmap.rst b/source/Roadmap.rst
@@ -1,3 +1,4 @@
+.. _Roadmap:
 
 Roadmap
 =======
@@ -8,7 +9,7 @@ Roadmap
 
 Please see the page of the upcoming distribution `Eloquent Elusor <Releases/Release-Eloquent-Elusor>` for more information what is planned to be part of that release.
 
-Please see the `Distributions page <Releases>` for the timeline of and information about future distributions.
+Please see the :ref:`Distributions page <Releases>` for the timeline of and information about future distributions.
 
 For more information on the design of ROS 2 please see `design.ros2.org <http:https://design.ros2.org>`__.
 The core code for ROS 2 is on the `ros2 github organization <https://github.com/ros2>`__.

diff --git a/source/Troubleshooting.rst b/source/Troubleshooting.rst
@@ -1,3 +1,4 @@
+.. _Troubleshooting:
 
 Troubleshooting
 ===============

diff --git a/source/Tutorials.rst b/source/Tutorials.rst
@@ -1,3 +1,4 @@
+.. _Tutorials:
 
 Tutorials
 =========

diff --git a/source/index.rst b/source/index.rst
@@ -1,141 +1,96 @@
 
-ROS 2
-=====
-
-Overview
---------
+ROS 2 Documentation
+===================
 
 .. toctree::
  :titlesonly:
  :maxdepth: 1
+ :hidden:
 
  Installation
- Roadmap
- Releases
- Concepts
- Features
  Tutorials
+ Concepts
  Troubleshooting
  Contributing
+ Contact
+ ROSCon-Content
+ Releases
+ Features
+ Roadmap
  Governance
  Marketing
  Related-Projects
- Contact
- About
 
-The Robot Operating System (ROS) is a set of software libraries and tools that help you build robot applications.
+The Robot Operating System (ROS) is a set of software libraries and tools for building robot applications.
 From drivers to state-of-the-art algorithms, and with powerful developer tools, ROS has what you need for your next robotics project.
 And it's all open source.
 
-Here you will find documentation on how to install and use software from **ROS 2**, which is a new version of ROS that is under heavy development.
-See below for more information on ROS 2.
-Also have a look at our `promotional material <Marketing>`.
+Since ROS was started in 2007, a lot has changed in the robotics and ROS community.
+The goal of the ROS 2 project is to adapt to these changes, leveraging what is great about ROS 1 and improving what isn’t.
 
-If you're looking for information on ROS 1 (i.e., ROS as it has existed for several years and what you might be using right now), check the `ROS website <http:https://www.ros.org>`__ or the `documentation wiki <http:https://wiki.ros.org>`__.
+Here you will find the official documentation on **ROS 2**, the newest version of ROS.
 
-**Before you proceed here, please read the** `features page <Features>` **to get an idea of what is in the current ROS 2 release.**
+If you're looking for documentation on ROS 1 (i.e., ROS as it has existed for several years, and what you might be using right now),
+check the `ROS wiki <http:https://wiki.ros.org>`__.
 
-Releases
---------
+Where to start
+--------------
 
-See `the releases page <Releases>`.
+Newcomers and experienced ROS users should consult this overview of our user-centric content to find what they're looking for.
 
-Installation
-------------
+* :ref:`Installation <InstallationGuide>` pages will help you setup ROS 2 for the first time.
+ You can choose your platform as well as the installation type and distribution that suits your needs.
 
-See `the installation page <Installation>`.
+* :ref:`Tutorials <Tutorials>` walk you through learning ROS 2,
+ whether you're learning from scratch or looking for guidance on achieving more specific goals.
 
-Tutorials and Features
-----------------------
+* :ref:`Concepts <ConceptsHome>` are high-level explanations and background information on core ROS 2 concepts,
+ which should provide some context for topics covered in the tutorials.
 
-ROS 2 is under heavy development.
+* :ref:`Troubleshooting <Troubleshooting>` guides cover some specific common cases where issues can arise.
 
-You can check out the `tutorials page <Tutorials>` to see a range of examples of what the system can do in its current state, if it fits your project *today* depending on the exact requirement.
+* :ref:`Contributing <Contributing>` is what makes ROS 2 great!
+ We have guides on best practices and methodology for contributing new ROS 2 content as well as migrating existing content from ROS 1 to ROS 2.
 
-For details of the current features, see `features status page <Features>`.
+* :ref:`Getting help <Help>` is always encouraged.
+ Here you'll find several ways to get answers to your questions or start a discussion.
 
-If migrating code from ROS to ROS 2, check `the migration guide <Contributing/Migration-Guide>`.
+Learn more
+^^^^^^^^^^
 
-What's ahead
-------------
+* `design.ros2.org <http:https://design.ros2.org>`__ contains various articles on the design decisions behind ROS 2, like:
+ * `Why ROS 2? <http:https://design.ros2.org/articles/why_ros2.html>`__
+ * `ROS on DDS <http:https://design.ros2.org/articles/ros_on_dds.html>`__
+ * `Changes between ROS 1 and ROS 2 <http:https://design.ros2.org/articles/changes.html>`__
 
-ROS 2 is currently planning to release new versions every six month (which is twice as often as ROS 1) to give the community members an opportunity to provide early feedback on the evolving system.
-See the `Roadmap <Roadmap>` for details on the planned upcoming features for ROS 2.
+* The code for ROS 2 is open source and broken into various repositories.
+ You can find the code for most of the repositories on the `ros2 github organization <https://github.com/ros2>`__.
 
-Contributing
-------------
+* `awesome-ros2 <https://fkromer.github.io/awesome-ros2>`__ is a "cheat sheet" style quick reference for ROS 2 packages and resources to help GitHub users get to know ROS 2.
 
-See `the contributing page <Contributing>` and `the developer guide <Contributing/Developer-Guide>` for details on how to contribute to ROS 2 developments.
+* This set of :ref:`ROSCon talks <ROSCon>` provides some context for various ROS 2 concepts.
 
-Governance
-----------
+About ROS 2
+-----------
 
-See `the governance page <Governance>`.
+If you're interested in the business and advancement side of the ROS 2 project,
+these pages provide high-level details in various related areas.
 
-Marketing
-----------
+* :ref:`Releases <Releases>` of past, present and future ROS 2 distributions, including dates and changes made between distributions.
 
-See `the marketing page <Marketing>`.
+* :ref:`Features <Features>` that are a part of the current ROS 2 release, plus content elaborating on each new feature.
 
-Reporting problems and asking questions
----------------------------------------
+* :ref:`Roadmap <Roadmap>` is a collection of feature ideas for ROS 2 not yet implemented, but coming soon.
 
-See `the contact page <Contact>`.
+* :ref:`Project governance <Governance>` is handled by the Technical Steering Committee, which you can learn more about here.
 
-About ROS 2
-===========
+* :ref:`Marketing <Marketing>` materials promoting ROS 2 can be downloaded from this page.
 
-Since ROS was started in 2007, a lot has changed in the robotics and ROS community.
-The goal of the ROS 2 project is to adapt to these changes, leveraging what is great about ROS 1 and improving what isn’t.
-There's a full article on the motivation of ROS 2 `here <http:https://design.ros2.org/articles/why_ros2.html>`__.
-
-Where to find more information
-------------------------------
-
-There are various articles on the design of ROS 2 at `design.ros2.org <http:https://design.ros2.org>`__\ , such as: `\ *Why ROS 2?* <http:https://design.ros2.org/articles/why_ros2.html>`__\ , `\ *ROS on DDS* <http:https://design.ros2.org/articles/ros_on_dds.html>`__\ , and `\ *Changes between ROS 1 and ROS 2* <http:https://design.ros2.org/articles/changes.html>`__.
-
-The code for ROS 2 is open source and broken into various repositories.
-You can find the code for most of the repositories on the `ros2 github organization <https://github.com/ros2>`__.
-
-`docs.ros2.org <http:https://docs.ros2.org>`__ contains current details about ROS 2 internal design and organization.
-
-`awesome-ros2 <https://fkromer.github.io/awesome-ros2>`__ is a "cheat sheet" style quick reference for ROS 2 packages and resources which will get (hopefully) listed on the `curated list of awesome lists <https://github.com/sindresorhus/awesome>`__ to help GitHub users to get to know ROS 2.
-
-The following `ROSCon <http:https://roscon.ros.org>`__ talks have been given on ROS 2 and provide information about the workings of ROS 2 and various demos:
-
-.. list-table::
- :header-rows: 1
-
- * - Title
- - Type
- - Links
- * - Hands-on ROS 2: A Walkthrough
- - ROSCon 2018 presentation
- - `slides <https://roscon.ros.org/2018/presentations/ROSCon2018_ROS2HandsOn.pdf>`__ / `video <https://vimeo.com/292693129>`__
- * - Launch for ROS 2
- - ROSCon 2018 presentation
- - `slides <https://roscon.ros.org/2018/presentations/ROSCon2018_launch.pdf>`__ / `video <https://vimeo.com/292699162>`__
- * - The ROS 2 vision for advancing the future of robotics development
- - ROSCon 2017 presentation
- - `slides <https://roscon.ros.org/2017/presentations/ROSCon%202017%20ROS2%20Vision.pdf>`__ / `video <https://vimeo.com/236161417>`__
- * - ROS 2 Update - summary of alpha releases, architectural overview
- - ROSCon 2016 presentation
- - `slides <http:https://roscon.ros.org/2016/presentations/ROSCon%202016%20-%20ROS%202%20Update.pdf>`__ / `video <https://vimeo.com/187696091>`__
- * - Evaluating the resilience of ROS2 communication layer
- - ROSCon 2016 presentation
- - `slides <http:https://roscon.ros.org/2016/presentations/rafal.kozik-ros2evaluation.pdf>`__ / `video <https://vimeo.com/187705229>`__
- * - State of ROS 2 - demos and the technology behind
- - ROSCon 2015 presentation
- - `slides <http:https://roscon.ros.org/2015/presentations/state-of-ros2.pdf>`__ / `video <https://vimeo.com/142151734>`__
- * - ROS 2 on "small" embedded systems
- - ROSCon 2015 presentation
- - `slides <http:https://roscon.ros.org/2015/presentations/ros2_on_small_embedded_systems.pdf>`__ / `video <https://vimeo.com/142150576>`__
- * - Real-time control in ROS and ROS 2
- - ROSCon 2015 presentation
- - `slides <http:https://roscon.ros.org/2015/presentations/RealtimeROS2.pdf>`__ / `video <https://vimeo.com/142621778>`__
- * - Why you want to use ROS 2
- - ROSCon 2014 presentation
- - `slides <http:https://www.osrfoundation.org/wordpress2/wp-content/uploads/2015/04/ROSCON-2014-Why-you-want-to-use-ROS-2.pdf>`__ / `video <https://vimeo.com/107531013>`__
- * - Next-generation ROS: Building on DDS
- - ROSCon 2014 presentation
- - `slides <http:https://roscon.ros.org/2014/wp-content/uploads/2014/07/ROSCON-2014-Next-Generation-of-ROS-on-top-of-DDS.pdf>`__ / `video <https://vimeo.com/106992622>`__
+About this documentation
+------------------------
+
+We're always working hard on improving our documentation.
+You can help by submitting pull requests for fixes or issues for suggestions on `our GitHub repository <http:https://github.com/ros2/ros2_documentation>`__.
+
+Written purely in `ReST markup format <http:https://docutils.sourceforge.net/rst.html>`__, it is processed using Sphinx during `ROSIndex <https://github.com/ros-infrastructure/rosindex>`__ builds.
+`Intersphinx support <Contributing/Inter-Sphinx-Support>` is readily available for cross-linking package specific entities.