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.
0xDEC0DE · Jul 9, 2024 · cc9bf00 · cc9bf00
1 parent 9e265ee
commit cc9bf00
Show file tree

Hide file tree

Showing 9 changed files with 62 additions and 96 deletions.
diff --git a/doc/en/_static/pytest-custom.css b/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%;
+ }
+}
diff --git a/doc/en/_templates/globaltoc.html b/doc/en/_templates/globaltoc.html
diff --git a/doc/en/_templates/relations.html b/doc/en/_templates/relations.html
diff --git a/doc/en/_templates/sidebar/brand.html b/doc/en/_templates/sidebar/brand.html
diff --git a/doc/en/_templates/sidebarintro.html b/doc/en/_templates/sidebarintro.html
diff --git a/doc/en/_templates/style.html b/doc/en/_templates/style.html
diff --git a/doc/en/conf.py b/doc/en/conf.py
@@ -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
 

diff --git a/doc/en/contents.rst b/doc/en/contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _toc:
 
 Full pytest documentation

diff --git a/doc/en/index.rst b/doc/en/index.rst
@@ -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:/pytest-dev/pytest/>
+ Issue Tracker <https:/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