From 8410d9ac549c5a743a55350bce2ac4c6c592fa98 Mon Sep 17 00:00:00 2001
From: Daniele Procida <daniele@vurt.org>
Date: Fri, 12 Mar 2021 22:57:53 +0000
Subject: [PATCH] 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.
---
 doc/en/_templates/globaltoc.html           | 14 +++++++++++---
 doc/en/contents.rst                        | 18 +++++++++++++-----
 doc/en/{ => explanation}/anatomy.rst       |  0
 doc/en/{ => explanation}/fixtures.rst      |  0
 doc/en/{ => explanation}/flaky.rst         |  0
 doc/en/{ => explanation}/goodpractices.rst |  2 +-
 doc/en/explanation/index.rst               | 13 +++++++++++++
 doc/en/{ => explanation}/pythonpath.rst    |  0
 doc/en/how-to/index.rst                    | 21 +++++++++++++++++++++
 doc/en/reference/index.rst                 | 19 +++++++++++++++++++
 10 files changed, 78 insertions(+), 9 deletions(-)
 rename doc/en/{ => explanation}/anatomy.rst (100%)
 rename doc/en/{ => explanation}/fixtures.rst (100%)
 rename doc/en/{ => explanation}/flaky.rst (100%)
 rename doc/en/{ => explanation}/goodpractices.rst (99%)
 create mode 100644 doc/en/explanation/index.rst
 rename doc/en/{ => explanation}/pythonpath.rst (100%)
 create mode 100644 doc/en/how-to/index.rst
 create mode 100644 doc/en/reference/index.rst

diff --git a/doc/en/_templates/globaltoc.html b/doc/en/_templates/globaltoc.html
index 4069e59eb..b6e74e8fb 100644
--- a/doc/en/_templates/globaltoc.html
+++ b/doc/en/_templates/globaltoc.html
@@ -2,12 +2,20 @@
 
 <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>
diff --git a/doc/en/contents.rst b/doc/en/contents.rst
index 45f26cc12..16c8f273b 100644
--- a/doc/en/contents.rst
+++ b/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
diff --git a/doc/en/anatomy.rst b/doc/en/explanation/anatomy.rst
similarity index 100%
rename from doc/en/anatomy.rst
rename to doc/en/explanation/anatomy.rst
diff --git a/doc/en/fixtures.rst b/doc/en/explanation/fixtures.rst
similarity index 100%
rename from doc/en/fixtures.rst
rename to doc/en/explanation/fixtures.rst
diff --git a/doc/en/flaky.rst b/doc/en/explanation/flaky.rst
similarity index 100%
rename from doc/en/flaky.rst
rename to doc/en/explanation/flaky.rst
diff --git a/doc/en/goodpractices.rst b/doc/en/explanation/goodpractices.rst
similarity index 99%
rename from doc/en/goodpractices.rst
rename to doc/en/explanation/goodpractices.rst
index 4b3c0af10..77c176182 100644
--- a/doc/en/goodpractices.rst
+++ b/doc/en/explanation/goodpractices.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.
diff --git a/doc/en/explanation/index.rst b/doc/en/explanation/index.rst
new file mode 100644
index 000000000..518fac999
--- /dev/null
+++ b/doc/en/explanation/index.rst
@@ -0,0 +1,13 @@
+:orphan:
+
+Explanation
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   anatomy
+   fixtures
+   goodpractices
+   flaky
+   pythonpath
diff --git a/doc/en/pythonpath.rst b/doc/en/explanation/pythonpath.rst
similarity index 100%
rename from doc/en/pythonpath.rst
rename to doc/en/explanation/pythonpath.rst
diff --git a/doc/en/how-to/index.rst b/doc/en/how-to/index.rst
new file mode 100644
index 000000000..c206a3057
--- /dev/null
+++ b/doc/en/how-to/index.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
diff --git a/doc/en/reference/index.rst b/doc/en/reference/index.rst
new file mode 100644
index 000000000..b62484cdf
--- /dev/null
+++ b/doc/en/reference/index.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