Merge pull request #78 from hungpham2511/impr-doc

Some improvements in docs
hungpham2511 · Feb 22, 2020 · 7bd53f1 · 7bd53f1
2 parents 60fcfe2 + b4f4b7e
commit 7bd53f1
Show file tree

Hide file tree

Showing 13 changed files with 270 additions and 267 deletions.
diff --git a/docs/source/FAQs.rst b/docs/source/FAQs.rst
diff --git a/docs/source/_static/toppra_illus.png b/docs/source/_static/toppra_illus.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -41,9 +41,8 @@
               'sphinx.ext.napoleon',
               'sphinx.ext.viewcode',
               'sphinx.ext.intersphinx',
-              'nbsphinx'
-]
- # Add mappings
+              'nbsphinx']
+
 intersphinx_mapping = {
     'urllib3': ('http://urllib3.readthedocs.org/en/latest', None),
     'python': ('http://docs.python.org/3', None),
@@ -95,7 +94,6 @@
 
 # -- Options for HTML output ----------------------------------------------
 
-
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
@@ -116,14 +114,15 @@
     'description': 'A robotic motion planning library for path-parametrization',
     'fixed_sidebar': True,
     "sidebar_width": "270px",
-    "page_width": "1240px",
+    "page_width": "1040px",
     "show_related": True}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -133,12 +132,12 @@
 html_sidebars = {
     '**': [
         'about.html',
-        'navigation.html',
+        'localtoc.html',
         'relations.html',  # needs 'show_related': True theme option to display
         'searchbox.html',
     ]
 }
-
+sidebar_collapse = True
 
 # -- Options for HTMLHelp output ------------------------------------------
 
@@ -190,6 +189,8 @@
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
+
+
 texinfo_documents = [
     (master_doc, 'TOPP-RA', 'TOPP-RA Documentation',
      author, 'TOPP-RA', 'One line description of project.',
@@ -198,3 +199,5 @@
 
 
 
+html_theme = 'alabaster'
+html_static_path = ['_static']
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,68 +1,54 @@
-.. TOPP-RA documentation master file, created by
-   sphinx-quick-start on Sat Nov 18 00:03:54 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
+.. TOPP-RA documentation master file
 **TOPP-RA**: Path-parameterization for robots
 ===================================================
 
-
 .. image:: https://circleci.com/gh/hungpham2511/toppra/tree/develop.svg?style=svg
     :target: https://circleci.com/gh/hungpham2511/toppra/tree/develop
 
 .. image:: https://readthedocs.org/projects/toppra/badge/?version=latest
     :target: https://toppra.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
 
-**TOPP-RA** is a library for computing the time-optimal path
-parametrization for robots subject to kinematic and dynamic
-constraints.  In general, given the inputs:
 
-1. a geometric path `p(s)`, `s` in `[0, s_end]` ;
+Overview
+-----------
+
+
+TOPP-RA is a library for computing path parametrizations for geometric
+paths subject to certain forms of kinematic and dynamic constraints
+Simply speaking given
+
+1. a smooth geometric path :math:`p(s), s \in [0, s_{end}]` ;
 2. a list of constraints on joint velocity, joint accelerations, tool
    Cartesian velocity, et cetera.
 
-**TOPP-RA** returns the time-optimal path parameterization: `s_dot
-(s)`, from which the fastest trajectory `q(t)` that satisfies the
-given constraints can be found. All of this is done in a few
-milliseconds.
-
-Features
----------
+TOPP-RA can produce the time-optimal path parameterization
+:math:`s_{dot} (s)`, from which the fastest trajectory `q(t)` that
+satisfies the given constraints can be found. All of this is done in a
+few milliseconds.  There are some additional features that make it
+easier to generate high-quality motions for robots:
 
 1. Return the time-optimal parametrization or a parametrization with
    specified duration subject to constraints.
 2. Able to handle multiple constraint types:
-  1. joint torque, velocity and acceleration bounds;
-  2. *robust* joint torque, velocity and acceleration bounds;
-  3. Cartesian acceleration bounds;
-  4. contact stability for legged robots.
 3. Automatic grid-points selection.
 
-Applications
-------------
-
-**(Feb, 2019)** TOPP-RA was used to plan *critically fast*
-motions for robots doing bin picking with suction cup. Here
-*critically fast* motions are those that are fastest possible given
-the limited suction power and object weight. See the video below for
-more detail!
-
-.. raw:: html
-
-   <iframe width="560" height="315" src="https://www.youtube.com/embed/b9H-zOYWLbY" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+.. figure:: _static/toppra_illus.png
+
+   This is the time-optimal joint trajectory for a robot subject to
+   joint accelerations and velocities constraints computed using
+   TOPP-RA. See :ref:`tutorials` for more examples.
+
+User guide
+--------------
 
+.. toctree::
+   :maxdepth: 2
 
-If you find this interesting, feel free to check out the paper:
-`«Critically fast pick-and-place with suction cups»
-<https://www.researchgate.net/publication/327570258_Critically_fast_pick-and-place_with_suction_cups>`_. This
-paper has been presented at ICRA 2019.
+   installation
+   tutorials
+   notes
 
-User Guide
-----------
-
-You can find on this page :ref:`installation`, :ref:`tutorials`, some
-:ref:`notes` and :ref:`module_ref`.
 
 Citing TOPP-RA!
 ----------------
@@ -77,13 +63,21 @@ Bug reports and supports
 -------------------------
 Please report any issues, questions via `Github issues tracker <https://github.com/hungpham2511/toppra/issues>`_.
 
-.. toctree::
-   :hidden:
-   :maxdepth: 3
+Applications
+------------
+
+**(Feb, 2019)** TOPP-RA was used to plan *critically fast*
+motions for robots doing bin picking with suction cup. Here
+*critically fast* motions are those that are fastest possible given
+the limited suction power and object weight. See the video below for
+more detail!
+
+.. raw:: html
+
+   <iframe width="560" height="315" src="https://www.youtube.com/embed/b9H-zOYWLbY" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
-   installation
-   tutorials
-   notes
-   FAQs
-   modules
 
+If you find this interesting, feel free to check out the paper:
+`«Critically fast pick-and-place with suction cups»
+<https://www.researchgate.net/publication/327570258_Critically_fast_pick-and-place_with_suction_cups>`_. This
+paper has been presented at ICRA 2019.
diff --git a/docs/source/modules.rst b/docs/source/modules.rst