Improve how the documentation sidebar is managed

Move away from injecting unstyled HTML into the sidebar, to using
Furo's default sidebar with Sphinx's `doctree` instead.

This also includes moving to a more typical Sphinx documentation
structure with the `index` page serving as the "root" of the `doctree`
for Sphinx.

Additionally, move custom stylesheets into a `pytest-custom.css` file
and use standard Sphinx tooling to inject these styles.

Author: pradyunsg

doc/en/_static/pytest-custom.css

@@ -0,0 +1,21 @@
+/* Tweak how the sidebar logo is presented */
+.sidebar-logo {
+  width: 70%;
+}
+.sidebar-brand {
+  padding: 0;
+}
+
+/* The landing pages' sidebar-in-content highlights */
+#features ul {
+  padding-left: 1rem;
+  list-style: none;
+}
+#features ul li {
+  margin-bottom: 0;
+}
+@media (min-width: 46em) {
+  #features {
+    width: 50%;
+  }
+}

doc/en/_templates/globaltoc.html

@@ -25,7 +25,7 @@
 # -- General configuration -------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-root_doc = "contents"
+root_doc = "index"
 extensions = [
     "pygments_pytest",
     "sphinx.ext.autodoc",
@@ -150,35 +150,19 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
+html_theme_options = {"sidebar_hide_name": True}
+
+html_static_path = ["_static"]
+html_css_files = [
+    "pytest-custom.css",
+]
+
 html_title = "pytest documentation"
 html_short_title = f"pytest-{release}"
 
-html_logo = "img/pytest_logo_curves.svg"
+html_logo = "_static/pytest1.png"
 html_favicon = "img/favicon.png"
 
-html_sidebars = {
-    "index": [
-        "sidebar/brand.html",
-        "sidebar/search.html",
-        "sidebar/scroll-start.html",
-        "sidebarintro.html",
-        "globaltoc.html",
-        "links.html",
-        "sidebar/scroll-end.html",
-        "style.html",
-    ],
-    "**": [
-        "sidebar/brand.html",
-        "sidebar/search.html",
-        "sidebar/scroll-start.html",
-        "globaltoc.html",
-        "relations.html",
-        "links.html",
-        "sidebar/scroll-end.html",
-        "style.html",
-    ],
-}
-
 html_use_index = False
 html_show_sourcelink = False
 

doc/en/_templates/relations.html

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _toc:
 
 Full pytest documentation

doc/en/_templates/sidebar/brand.html

@@ -1,5 +1,3 @@
-:orphan:
-
 .. _features:
 
 .. sidebar:: **Next Open Trainings and Events**
@@ -13,6 +11,36 @@
 pytest: helps you write better programs
 =======================================
 
+.. toctree::
+    :hidden:
+
+    getting-started
+    how-to/index
+    reference/index
+    explanation/index
+    example/index
+
+.. toctree::
+    :caption: About the project
+    :hidden:
+
+    changelog
+    contributing
+    backwards-compatibility
+    sponsor
+    tidelift
+    license
+    contact
+
+.. toctree::
+    :caption: Useful links
+    :hidden:
+
+    pytest @ PyPI <https://pypi.org/project/pytest/>
+    pytest @ GitHub <https://github.com/pytest-dev/pytest/>
+    Issue Tracker <https://github.com/pytest-dev/pytest/issues>
+    PDF Documentation <https://media.readthedocs.org/pdf/pytest/latest/pytest.pdf>
+
 .. module:: pytest
 
 The ``pytest`` framework makes it easy to write small, readable tests, and can