Improve TOC structure (#988)

* Add section headers to the toc tree
* Add a "Guides" section and put the libraries document there
* Move the link to the typing documentation into the "Reference" section

Cf. #845

Author: srittau

docs/index.rst

@@ -1,30 +1,37 @@
 *************************
 Static Typing with Python
 *************************
+
+.. Introduction
+.. ============
 .. 
 .. .. toctree::
 ..    :maxdepth: 2
-..    :caption: Contents:
 .. 
 ..    source/introduction
 
+Guides
+======
+
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
-   source/reference
+   source/guides
 
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   source/reference
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`search`
 
-Python Language Documentation
-=============================
-
-* `typing Module Documentation <https://docs.python.org/3/library/typing.html>`_
-
 Discussions and Support
 =======================
 

docs/source/guides.rst

@@ -0,0 +1,9 @@
+******************
+Type System Guides
+******************
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   libraries

docs/source/reference.rst

@@ -6,9 +6,8 @@ Type System Reference
    :maxdepth: 2
    :caption: Contents:
 
-   libraries
    stubs
-
+   typing Module Documentation <https://docs.python.org/3/library/typing.html>
 
 .. The following pages are desired in a new TOC which will cover multiple
 .. topics. For now, they are not linked because the pages are empty.