Fix up some documentation quirks

Fixed up documentation so that resulting docs look and feel better.

Related-Bug: #1588013

Change-Id: I25633be87fb81ca5e66b644b2309210a4c83f01a

README.rst

@@ -1,5 +1,5 @@
 Networking-odl
-==============
+--------------
 
 OpenStack networking-odl is a library of drivers and plugins that integrates
 OpenStack Neutron API with OpenDaylight Backend. For example it has ML2
@@ -18,8 +18,9 @@ link can be checked:
    http://docs.openstack.org/developer/neutron/
 
 
-External Resources:
-===================
+External Resources
+~~~~~~~~~~~~~~~~~~
 
 The OpenDaylight homepage:
+
    http://www.opendaylight.org/

doc/source/devref/index.rst

@@ -20,7 +20,7 @@ level design and implementation details.
 
 
 Contents:
---------------------------------
+
 .. toctree::
    :maxdepth: 2
 
@@ -30,7 +30,7 @@ Contents:
 
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

doc/source/index.rst

@@ -1,33 +1,30 @@
-.. networking-odl documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to networking-odl's documentation!
-========================================================
+==========================================
 
-Contents:
+.. include:: ../../README.rst
+
+General Documentation
+---------------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   readme
    installation
    usage
    contributing
-   specs
 
 Developer Docs
-==============
+--------------
 
 .. toctree::
    :maxdepth: 1
 
    devref/index
+   specs
 
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

doc/source/readme.rst

@@ -1 +0,0 @@
-.. include:: ../../README.rst

doc/source/specs.rst

@@ -6,12 +6,10 @@
 
  neutron networking-odl specs documentation master file
 
-=============================================
 Neutron networking-odl Project Specifications
 =============================================
 
-Specs
-=====
+Specs:
 
 .. toctree::
    :glob:
@@ -19,8 +17,7 @@ Specs
 
    specs/*
 
-==================
 Indices and tables
-==================
+------------------
 
 * :ref:`search`