Added how-to and reference directories.

Moved various documents into subdirectories, how-to and
reference.

Updated multiple links to use `:ref:` instead of `:doc:`,
meaning that files can henceforth be moved around without
breaking references.

Author: evildmp

changelog/5105.doc.rst

@@ -1 +1 @@
-Add automatically generated :doc:`plugin_list`. The list is updated on a periodic schedule.
+Add automatically generated :ref:`plugin-list`. The list is updated on a periodic schedule.

doc/en/contents.rst

@@ -23,18 +23,18 @@ How-to guides
 .. toctree::
    :maxdepth: 2
 
-   usage
-   existingtestsuite
-   assert
-   mark
-   monkeypatch
-   tmpdir
-   capture
-   skipping
-   parametrize
-   plugins
-   nose
-   bash-completion
+   how-to/usage
+   how-to/existingtestsuite
+   how-to/assert
+   how-to/mark
+   how-to/monkeypatch
+   how-to/tmpdir
+   how-to/capture
+   how-to/skipping
+   how-to/parametrize
+   how-to/plugins
+   how-to/nose
+   how-to/bash-completion
 
 
 Reference guides
@@ -43,17 +43,17 @@ Reference guides
 .. toctree::
    :maxdepth: 2
 
-   fixture
-   warnings
-   doctest
-   cache
-   unittest
-   xunit_setup
-   plugin_list
-   writing_plugins
-   logging
-   customize
-   reference
+   reference/fixture
+   reference/warnings
+   reference/doctest
+   reference/cache
+   reference/unittest
+   reference/xunit_setup
+   reference/plugin_list
+   reference/writing_plugins
+   reference/logging
+   reference/customize
+   reference/reference
 
 
 Further topics

doc/en/example/index.rst

@@ -13,12 +13,12 @@ answers.
 
 For basic examples, see
 
-- :doc:`../getting-started` for basic introductory examples
+- :ref:`get-started` for basic introductory examples
 - :ref:`assert` for basic assertion examples
 - :ref:`Fixtures <fixtures>` for basic fixture/setup examples
 - :ref:`parametrize` for basic test function parametrization
-- :doc:`../unittest` for basic unittest integration
-- :doc:`../nose` for basic nosetests integration
+- :ref:`unittest` for basic unittest integration
+- :ref:`noseintegration` for basic nosetests integration
 
 The following examples aim at various use cases you might encounter.
 

doc/en/getting-started.rst

@@ -1,3 +1,5 @@
+.. _get-started:
+
 Get Started
 ===================================
 

doc/en/assert.rst renamed to doc/en/how-to/assert.rst

@@ -1,3 +1,4 @@
+.. _monkeypatching:
 
 How to monkeypatch/mock modules and environments
 ================================================================