Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issue #12290 - Docs using Furo Theme W/ Dark Mode #12326

Merged
merged 11 commits into from
May 21, 2024
Merged
1 change: 1 addition & 0 deletions AUTHORS
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,7 @@ Sadra Barikbin
Saiprasad Kale
Samuel Colvin
Samuel Dion-Girardeau
Samuel Jirovec
Samuel Searles-Bryant
Samuel Therrien (Avasam)
Samuele Pedroni
Expand Down
4 changes: 0 additions & 4 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,6 @@ Contribution getting started
Contributions are highly welcomed and appreciated. Every little bit of help counts,
so do not hesitate!

.. contents::
:depth: 2
:backlinks: none


.. _submitfeedback:

Expand Down
1 change: 1 addition & 0 deletions changelog/12290.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Updated Sphinx theme to use Furo instead of Flask, enabling Dark mode theme.
File renamed without changes
7 changes: 7 additions & 0 deletions doc/en/_templates/sidebar/brand.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<style>
.logo {text-align: center;}
</style>

<a class="logo" href="{{ pathto('contents') }}">
<img src="{{ pathto('_static/pytest1.png', 1) }}" width="70%" height="70%" text="Pytest Logo"/>
</a>
14 changes: 0 additions & 14 deletions doc/en/_templates/slim_searchbox.html

This file was deleted.

7 changes: 7 additions & 0 deletions doc/en/_templates/style.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<style>
ul {list-style: none;}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samjirovec @The-Compiler @nicoddemus @bluetech this makes bullet lists in the change log invisible. Well, globally, really. There are plenty of examples @ https://docs.pytest.org/en/latest/changelog.html#new-features and in the events widget too. What was the intention here?

Oh, @ferdnyc already called out this problem in #12326 (comment)...

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, to be honest I got as far as realizing that the missing bullets were intentional and explicit in the PR's local CSS, and immediately dropped it. Since it was clearly not a bug or an unexpected change, I assumed the decision to hide list markers was an aesthetic choice (possibly discussed elsewhere) for the new-theme look of the docs.

If that wasn't the case, and it was actually "snuck in" with the new theme (not in a malicious sense, just meaning that it wasn't explicitly stated in the PR/commit texts, and probably flew under people's radar), then I should've made a bigger fuss. With such sweeping changes completely transforming the appearance of the docs, it's easy to overlook a difference like that. My bad for not following up on it better.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From discussions, I don't think people realized the extent of the effect of this choice and the lack of granularity. Also, many might not be qualified to spot these problems easily. Thanks for trying to warn people, though :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not recall any discussion regarding intentionally hiding those bullet points... I personally would prefer them on.

Perhaps we can follow up another PR enabling them back? That would be a place for anybody who remembers that decision to voice that, but otherwise I suspect indeed this just flew under the radar, or was something that looked better on the old theme.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, as #12581

li {margin: 0.4em 0;}
@media (min-width: 46em) {
#features {width: 50%;}
}
</style>
Copy link

@ferdnyc ferdnyc May 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
</style>
@media (min-width: 46em) {
#features {width: 50%;}
}
</style>

(To widen the trainings & events sidebar. At 46em the width becomes 100%, messing with that looks weird.)

30 changes: 11 additions & 19 deletions doc/en/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,7 @@
#
# The full version, including alpha/beta/rc tags.
# The short X.Y version.
import os
import shutil
import sys
from textwrap import dedent
from typing import TYPE_CHECKING

Expand Down Expand Up @@ -65,7 +63,6 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
"pallets_sphinx_themes",
"pygments_pytest",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
Expand Down Expand Up @@ -140,10 +137,6 @@
# output. They are ignored by default.
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"


# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

Expand Down Expand Up @@ -216,12 +209,9 @@

# -- Options for HTML output ---------------------------------------------------

sys.path.append(os.path.abspath("_themes"))
html_theme_path = ["_themes"]

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "flask"
html_theme = "furo"

# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
Expand Down Expand Up @@ -266,18 +256,24 @@

html_sidebars = {
"index": [
"slim_searchbox.html",
"sidebar/brand.html",
"sidebar/search.html",
"sidebar/scroll-start.html",
"sidebarintro.html",
"globaltoc.html",
"links.html",
"sourcelink.html",
"sidebar/scroll-end.html",
"style.html",
],
"**": [
"slim_searchbox.html",
"sidebar/brand.html",
"sidebar/search.html",
"sidebar/scroll-start.html",
"globaltoc.html",
"relations.html",
"links.html",
"sourcelink.html",
"sidebar/scroll-end.html",
"style.html",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh wow, this is a bad way to do things. See https://pradyunsg.me/furo/customisation/injecting/#css-or-js for the guidance from the theme for how to inject CSS.

],
}

Expand Down Expand Up @@ -337,10 +333,6 @@
)
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
latex_logo = "img/pytest1.png"

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
Expand Down
4 changes: 0 additions & 4 deletions doc/en/deprecations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,6 @@ This page lists all pytest features that are currently deprecated or have been r
The objective is to give users a clear rationale why a certain feature has been removed, and what alternatives
should be used instead.

.. contents::
:depth: 3
:local:


Deprecated Features
-------------------
Expand Down
17 changes: 8 additions & 9 deletions doc/en/index.rst
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
:orphan:

.. sidebar:: Next Open Trainings and Events
.. _features:

- `Professional Testing with Python <https://python-academy.com/courses/python_course_testing.html>`_, via `Python Academy <https://www.python-academy.com/>`_ (3 day in-depth training):
* **June 11th to 13th 2024**, Remote
* **March 4th to 6th 2025**, Leipzig, Germany / Remote
- `pytest development sprint <https://github.com/pytest-dev/sprint>`_, **June 17th -- 22nd 2024**
- pytest tips and tricks for a better testsuite, `Europython 2024 <https://ep2024.europython.eu/>`_, **July 8th -- 14th 2024** (3h), Prague
.. sidebar:: **Next Open Trainings and Events**

Also see :doc:`previous talks and blogposts <talks>`.
- `Professional Testing with Python <https://python-academy.com/courses/python_course_testing.html>`_, via `Python Academy <https://www.python-academy.com/>`_ (3 day in-depth training):
* **June 11th to 13th 2024**, Remote
* **March 4th to 6th 2025**, Leipzig, Germany / Remote
- `pytest development sprint <https://github.com/pytest-dev/sprint>`_, **June 17th -- 22nd 2024**
- pytest tips and tricks for a better testsuite, `Europython 2024 <https://ep2024.europython.eu/>`_, **July 8th -- 14th 2024** (3h), Prague

.. _features:
Also see :doc:`previous talks and blogposts <talks>`

pytest: helps you write better programs
=======================================
Expand All @@ -25,7 +25,6 @@ scale to support complex functional testing for applications and libraries.

**PyPI package name**: :pypi:`pytest`


A quick example
---------------

Expand Down
3 changes: 0 additions & 3 deletions doc/en/reference/reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,6 @@ API Reference

This page contains the full reference to pytest's API.

.. contents::
:depth: 3
:local:

Constants
---------
Expand Down
4 changes: 2 additions & 2 deletions doc/en/requirements.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
pallets-sphinx-themes
pluggy>=1.5.0
pygments-pytest>=2.3.0
sphinx-removed-in>=0.2.0
Expand All @@ -8,4 +7,5 @@ sphinxcontrib-svg2pdfconverter
# Pin packaging because it no longer handles 'latest' version, which
# is the version that is assigned to the docs.
# See https://github.com/pytest-dev/pytest/pull/10578#issuecomment-1348249045.
packaging <22
packaging
furo
Loading