Merge pull request #8431 from evildmp/evolutionary-documentation-restructure

Moved documentation topics to group them by theme.

doc/en/_templates/globaltoc.html

@@ -3,11 +3,11 @@
 <ul>
   <li><a href="{{ pathto('index') }}">Home</a></li>
   <li><a href="{{ pathto('getting-started') }}">Get started</a></li>
-  <li><a href="{{ pathto('contents') }}">Contents</a></li>
-  <li><a href="{{ pathto('reference') }}">API Reference</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('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

@@ -7,38 +7,65 @@ Full pytest documentation
 
 .. `Download latest version as EPUB <http://media.readthedocs.org/epub/pytest/latest/pytest.epub>`_
 
+
+Start here
+-----------
+
 .. toctree::
    :maxdepth: 2
 
    getting-started
+
+
+How-to guides
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
    usage
    existingtestsuite
    assert
-   fixture
    mark
    monkeypatch
    tmpdir
    capture
-   warnings
-   doctest
    skipping
    parametrize
+   plugins
+   nose
+   bash-completion
+
+
+Reference guides
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   fixture
+   warnings
+   doctest
    cache
    unittest
-   nose
    xunit_setup
-   plugins
    plugin_list
    writing_plugins
    logging
+   customize
    reference
 
+
+Further topics
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
    goodpractices
    flaky
    pythonpath
-   customize
    example/index
-   bash-completion
 
    backwards-compatibility
    deprecations