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.

4 changes: 4 additions & 0 deletions doc/en/_templates/style.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
<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: 5px 0};
Copy link

Choose a reason for hiding this comment

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

CSS syntax nit, and because the theme measurements are all in ems:

Suggested change
li {margin: 5px 0};
li {margin: 0.4em 0;}

</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.)

20 changes: 11 additions & 9 deletions doc/en/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,7 @@

# 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 +266,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 +343,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
21 changes: 11 additions & 10 deletions doc/en/index.rst
Original file line number Diff line number Diff line change
@@ -1,15 +1,5 @@
:orphan:

.. sidebar:: Next Open Trainings and Events

- `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

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

.. _features:

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

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

.. note::
**Next Open Trainings and Events**

- `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

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


A quick example
---------------
Expand Down
1 change: 1 addition & 0 deletions doc/en/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,4 @@ sphinxcontrib-svg2pdfconverter
# is the version that is assigned to the docs.
# See https://github.com/pytest-dev/pytest/pull/10578#issuecomment-1348249045.
packaging <22
Copy link
Contributor

Choose a reason for hiding this comment

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

You should be able to unpin this too since this was pinned due to the existing theme: #10578 (comment)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

unpinned it + removed sphinx theme. This will affected only the light mode code snippets.

furo
Copy link
Member

Choose a reason for hiding this comment

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

Should also remove the pallets-sphinx-themes?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Definitely. Will remove this. + removing some extras based on #9788

Loading