Moved more sections from reference to how-to.

* re-ordered and grouped how-to guides in how-to landing page
* retitled moved documents appropriately
* separated writing plugins/writing hook functions into two documents

Author: evildmp

doc/en/contents.rst

@@ -24,18 +24,30 @@ How-to guides
    :maxdepth: 2
 
    how-to/usage
-   how-to/existingtestsuite
    how-to/assert
+   how-to/fixtures
    how-to/mark
-   how-to/monkeypatch
+   how-to/parametrize
    how-to/tmpdir
-   how-to/capture
+   how-to/monkeypatch
+   how-to/doctest
+   how-to/cache
+
+   how-to/logging
+   how-to/capture-stdout-stderr
+   how-to/capture-warnings
    how-to/skipping
-   how-to/parametrize
+
    how-to/plugins
+   how-to/writing_plugins
+   how-to/writing_hook_functions
+
+   how-to/existingtestsuite
+   how-to/unittest
    how-to/nose
+   how-to/xunit_setup
+
    how-to/bash-completion
-   how-to/fixtures
 
 
 Reference guides
@@ -45,14 +57,7 @@ Reference guides
    :maxdepth: 2
 
    reference/fixtures
-   reference/warnings
-   reference/doctest
-   reference/cache
-   reference/unittest
-   reference/xunit_setup
    reference/plugin_list
-   reference/writing_plugins
-   reference/logging
    reference/customize
    reference/reference
 

doc/en/explanation/fixtures.rst

@@ -6,6 +6,7 @@ About fixtures
 .. seealso:: :ref:`how-to-fixtures`
 .. seealso:: :ref:`Fixtures reference <reference-fixtures>`
 
+pytest fixtures are designed to be explicit, modular and scalable.
 
 What fixtures are
 -----------------

doc/en/how-to/assert.rst

@@ -1,16 +1,14 @@
+.. _`assert`:
 
 How to write and report assertions in tests
 ==================================================
 
-.. _`assertfeedback`:
 .. _`assert with the assert statement`:
-.. _`assert`:
-
 
 Asserting with the ``assert`` statement
 ---------------------------------------------------------
 
-``pytest`` allows you to use the standard python ``assert`` for verifying
+``pytest`` allows you to use the standard Python ``assert`` for verifying
 expectations and values in Python tests.  For example, you can write the
 following:
 

doc/en/reference/cache.rst renamed to doc/en/how-to/cache.rst

@@ -2,8 +2,8 @@
 .. _cache:
 
 
-Cache: working with cross-testrun state
-=======================================
+How to re-run failed tests and maintain state between test runs
+===============================================================
 
 
 

doc/en/how-to/capture.rst renamed to doc/en/how-to/capture-stdout-stderr.rst

@@ -1,7 +1,7 @@
 .. _`warnings`:
 
-Warnings Capture
-================
+How to capture warnings
+=======================
 
 
 

doc/en/reference/warnings.rst renamed to doc/en/how-to/capture-warnings.rst

@@ -1,6 +1,6 @@
 .. _doctest:
 
-Doctest integration for modules and test files
+How to run doctests
 =========================================================
 
 By default, all files matching the ``test*.txt`` pattern will

doc/en/reference/doctest.rst renamed to doc/en/how-to/doctest.rst

@@ -3,19 +3,60 @@
 How-to guides
 ================
 
+Core pytest functionality
+-------------------------
+
 .. toctree::
    :maxdepth: 1
 
    usage
-   existingtestsuite
    assert
+   fixtures
    mark
-   monkeypatch
+   parametrize
    tmpdir
-   capture
+   monkeypatch
+   doctest
+   cache
+
+test output and outcomes
+----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   logging
+   capture-stdout-stderr
+   capture-warnings
    skipping
-   parametrize
+
+Plugins
+----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
    plugins
+   writing_plugins
+   writing_hook_functions
+
+pytest and other test systems
+-----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   existingtestsuite
+   unittest
    nose
+   xunit_setup
+
+pytest development environment
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
    bash-completion
-   fixtures
+
+

doc/en/how-to/index.rst

@@ -1,10 +1,7 @@
 .. _logging:
 
-Logging
--------
-
-
-
+How to manage logging
+---------------------
 
 pytest captures log messages of level ``WARNING`` or above automatically and displays them in their own section
 for each failed test in the same manner as captured stdout and stderr.

doc/en/reference/logging.rst renamed to doc/en/how-to/logging.rst

@@ -2,8 +2,8 @@
 .. _`unittest.TestCase`:
 .. _`unittest`:
 
-unittest.TestCase Support
-=========================
+How to use ``unittest``-based tests with pytest
+===============================================
 
 ``pytest`` supports running Python ``unittest``-based tests out of the box.
 It's meant for leveraging existing ``unittest``-based test suites