Created a new Explanation section and new landing pages for main sections.

Added landing pages for:

How-to guides
Reference guides
Explanation

Added links to the main landing pages to the sidebar.

Author: evildmp

doc/en/_templates/globaltoc.html

@@ -2,12 +2,20 @@ <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
 
 <ul>
   <li><a href="{{ pathto('index') }}">Home</a></li>
+
   <li><a href="{{ pathto('getting-started') }}">Get started</a></li>
+  <li><a href="{{ pathto('how-to/index') }}">How-to guides</a></li>
+  <li><a href="{{ pathto('reference/index') }}">Reference guides</a></li>
+  <li><a href="{{ pathto('explanation/index') }}">Explanation</a></li>
+
   <li><a href="{{ pathto('example/index') }}">Examples</a></li>
-  <li><a href="{{ pathto('customize') }}">Customize</a></li>
-  <li><a href="{{ pathto('reference') }}">API Reference</a></li>
-  <li><a href="{{ pathto('plugin_list') }}">3rd party plugins</a></li>
+
+  <li><a href="{{ pathto('reference/customize') }}">Customize</a></li>
+  <li><a href="{{ pathto('reference/reference') }}">API Reference</a></li>
+  <li><a href="{{ pathto('reference/plugin_list') }}">3rd party plugins</a></li>
+
   <li><a href="{{ pathto('contents') }}">Complete table of contents</a></li>
+
   <li><a href="{{ pathto('changelog') }}">Changelog</a></li>
   <li><a href="{{ pathto('contributing') }}">Contributing</a></li>
   <li><a href="{{ pathto('backwards-compatibility') }}">Backwards Compatibility</a></li>

doc/en/contents.rst

@@ -57,17 +57,25 @@ Reference guides
    reference/reference
 
 
+Explanation
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   explanation/anatomy
+   explanation/fixtures
+   explanation/goodpractices
+   explanation/flaky
+   explanation/pythonpath
+
+
 Further topics
 -----------------
 
 .. toctree::
    :maxdepth: 2
 
-   anatomy
-   fixtures
-   goodpractices
-   flaky
-   pythonpath
    example/index
 
    backwards-compatibility

doc/en/anatomy.rst renamed to doc/en/explanation/anatomy.rst

@@ -48,7 +48,7 @@ Conventions for Python test discovery
   * ``test`` prefixed test functions or methods outside of class
   * ``test`` prefixed test functions or methods inside ``Test`` prefixed test classes (without an ``__init__`` method)
 
-For examples of how to customize your test discovery :doc:`example/pythoncollection`.
+For examples of how to customize your test discovery :doc:`/example/pythoncollection`.
 
 Within Python modules, ``pytest`` also discovers tests using the standard
 :ref:`unittest.TestCase <unittest.TestCase>` subclassing technique.

doc/en/fixtures.rst renamed to doc/en/explanation/fixtures.rst

@@ -0,0 +1,13 @@
+:orphan:
+
+Explanation
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   anatomy
+   fixtures
+   goodpractices
+   flaky
+   pythonpath

doc/en/flaky.rst renamed to doc/en/explanation/flaky.rst

@@ -0,0 +1,21 @@
+:orphan:
+
+How-to guides
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   usage
+   existingtestsuite
+   assert
+   mark
+   monkeypatch
+   tmpdir
+   capture
+   skipping
+   parametrize
+   plugins
+   nose
+   bash-completion
+   fixtures

doc/en/goodpractices.rst renamed to doc/en/explanation/goodpractices.rst

@@ -0,0 +1,19 @@
+:orphan:
+
+Reference guides
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   fixtures
+   warnings
+   doctest
+   cache
+   unittest
+   xunit_setup
+   plugin_list
+   writing_plugins
+   logging
+   customize
+   reference