Bug 1478711 - Docs: Fix navigation links

Previously the mixture of heading types was confusing the RTD theme,
causing the navigation sidebar to display at the top level not just
the page links, but links to subsections within those pages too.
The subsection names taken out of context were pretty confusing,
making it hard to navigate the docs.

docs/index.rst

@@ -1,17 +1,11 @@
-.. treeherder documentation master file, created by
-   sphinx-quickstart on Tue Mar 12 11:11:48 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to the Treeherder documentation!
 ========================================
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
    installation
+   ui/installation
    pulseload
    seta
    common_tasks
@@ -21,14 +15,5 @@ Contents:
    data_validation
    code_style
    troubleshooting
-   ui/index
    testcases
    admin
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/installation.rst

@@ -5,7 +5,7 @@ Installation
           instance of Treeherder. If you only want to hack on the UI,
           you can just setup a standalone webserver which accesses
           the server backend using node.js, which is much simpler.
-          See the :doc:`UI installation section <ui/installation>`.
+          See the :doc:`UI development section <ui/installation>`.
 
 
 Prerequisites
@@ -74,7 +74,7 @@ Starting a local Treeherder instance
     vagrant ~/treeherder$ yarn start:local
 
   This will build the UI code in the ``dist/`` folder and keep watching for
-  new changes (See the :doc:`UI installation section <ui/installation>` for more ways to work with the UI code).
+  new changes (See the :doc:`UI development section <ui/installation>` for more ways to work with the UI code).
 
 * Visit http://localhost:5000 in your browser (NB: port has changed). Note: There will be no data to display until the ingestion tasks are run.
 

docs/seta.rst

@@ -33,29 +33,14 @@ APIs
   * This API shows job failures that have been annotated with "fixed by commit"
 
 Local set up
-============
-After you set up Treeherder, ssh (3 different tabs) into the provisioned VM and follow these steps:
+------------
+After you set up Treeherder, ssh (3 different tabs) into the provisioned VM and run the following commands in each:
 
-1st tab
--------
-.. code-block:: bash
-
-   ./manage.py runserver
-
-2nd tab
--------
-.. code-block:: bash
-
-   yarn start:local
-
-3rd tab
--------
-.. code-block:: bash
-
-   ./manage.py initialize_seta
+* 1st tab: ``./manage.py runserver``
+* 2nd tab: ``yarn start:local``
+* 3rd tab: ``./manage.py initialize_seta``
 
-Try out the various APIs
-------------------------
+Then try out the various APIs:
 
 * http://localhost:5000/api/project/mozilla-inbound/seta/v1/job-priorities/?build_system_type=buildbot
 * http://localhost:5000/api/project/mozilla-inbound/seta/v1/job-priorities/?build_system_type=taskcluster
@@ -65,7 +50,7 @@ Try out the various APIs
   * This one won't work until https://bugzilla.mozilla.org/show_bug.cgi?id=1389123 is fixed
 
 Maintenance
-===========
+-----------
 
 Sometimes the default behaviour of SETA is not adequate (e.g. new jobs noticed get a 2 week expiration date & a high priority)
 when adding new platforms (e.g. stylo).
@@ -75,7 +60,7 @@ If you want to inspect the priorities for various jobs and platforms you can que
 Use this a starting query: https://sql.telemetry.mozilla.org/queries/14771/source#table
 
 Steps for adjusting jobs
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 To connect to Treeherder you need Heroku permissions. Run this from a treeherder checkout:
 
 .. code-block:: bash

docs/ui/installation.rst

@@ -1,5 +1,5 @@
-Installation
-============
+UI development
+==============
 
 It's possible to work on the UI without setting up the Vagrant VM.
 
@@ -80,7 +80,7 @@ If you would like to view the minified production version of the UI with Vagrant
 Once the build is complete, the minified version of the UI will now be accessible at http://localhost:8000 (NB: port 8000, unlike above).
 
 Validating JavaScript
-=====================
+---------------------
 
 We run our JavaScript code in the frontend through eslint_ to ensure
 that new code has a consistent style and doesn't suffer from common
@@ -95,7 +95,7 @@ To run eslint by itself, you may run the lint task:
      $ yarn lint
 
 Running the unit tests
-======================
+----------------------
 
 The unit tests for the UI are run with Karma_ and Jasmine_. React components are tested with enzyme_. At this time, these tests cannot be run inside of a Vagrant VM. To run the tests:
 
@@ -108,8 +108,6 @@ The unit tests for the UI are run with Karma_ and Jasmine_. React components are
 
 After the tests have finished, you can find a coverage report in the `coverage/` directory.
 
-Watching the test files
------------------------
 While working on the frontend, you may wish to watch JavaScript files and re-run tests
 automatically when files change. To do this, you may run the following command: