Opinions: Looks of the pytest docs?

[nicoddemus]

Since awhile now I feel that the documentation could use a face lift.

It seems to me it is not a single thing, it might be a bunch of small things/tweeks from some one who knows about design.

I've built the docs with the RTD theme (which I like) to try to give examples of what I'm trying to convey:

This is not bad, of course, but I have the feeling that the RTD theme is better:

Here is some things that I think are better in the second screenshot:

1. The overall font and styles seem better to read somehow (I can't point my finger at what exactly makes it better).
2. The function signature looks more like a header, as it should be I think.
3. The keywords (re.search, re.escape) have a nice highlight; in the first screenshot they are easy to miss in the middle of the text.
4. Nice use of colors to bring attention to some parts of the text (like the [source] link), without overusing colors.

Another example:

The first screenshot looks outdated, while the second one looks more modern to me somehow.

Of course those are all impressions of someone with zero talent for design, so take that as it is.

I'm not proposing here we should go and adopt the RTD theme, but I was wondering if anybody feels the same way? Perhaps someone with an eye on design (or even a professional) can critically look at our styles and provide suggestions of good improvements?

[The-Compiler]

Perhaps someone with an eye on design (or even a professional) can critically look at our styles and provide suggestions of good improvements?

I'd like to post this at https://opensourcedesign.net/jobs/

Given that we have some $16k in our OpenCollective account, what about posting a paid offer for a redesign (and not just a review) there?

[JPTIZ]

As a user (in the library's point of view), I agree: the first one looks like a bunch of text thrown everywhere, while the second has styles that enhances where sections begin, what things are important, and even the source link that I haven't noticed at first in the first screenshot but did almost instantly in the second one. It could be more friendly for newcomers too.

[nicoddemus]

Given that we have some $16k in our OpenCollective account, what about posting a paid offer for a redesign (and not just a review) there?

Definitely, I was going for that if a number of people would agree with the idea of a redesign. 👍

[jugmac00]

Many projects just use the RTD theme - and I think that's a great idea.

[AWhetter]

I agree with the sentiments of @JPTIZ. I've always found the current design difficult to read and I much prefer the RTD theme for readability. However I've never really been a fan of the RTD theme either. I think it's been looking a little dated for a while, and more importantly I don't think it's a clean looking as it could be.
I would love to see the Python community come up with something better, so a complete redesign would be a welcome change in my book.

[nicoddemus]

OK so it seems the majority is in favor of a change.

@The-Compiler since you mention you would like to post this over opensourcedesign.net, could you go ahead and do that? Thanks.

Not sure how much is the rate for this job though, but we will use our Open Collective account then.

[The-Compiler]

I started writing something:

The pytest framework (for Python) makes it easy to write small automated tests, yet scales to support complex functional testing for applications and libraries.

We recently identified some issues with the design of our documentation/website. We'd like someone to take a closer look at what seems problematic with the current design and [...]

Then I looked at the repository and saw that we're using a six year old snapshot (with some finetuning) of the design Flask uses.

It seems to live here nowadays: https://github.com/pallets/pallets-sphinx-themes

Maybe we should first update our theme to the latest Flask/Pallets one, and then coordinate with them so (if they want to), they can benefit from the same improvements?

[nicoddemus]

Maybe we should first update our theme to the latest Flask/Pallets one, and then coordinate with them so (if they want to), they can benefit from the same improvements?

Sure. Could you try to update the theme then? Perhaps it might be better already

[The-Compiler]

No time at the moment to take this on, I'm afraid - lots of stuff on my plate currently 😉

[nicoddemus]

I changed it just to take a look how it looks:

#6453

https://docs.pytest.org/en/use-standard-flask-theme/

[blueyed]

Why not try the "sphinx_rtd_theme" instead? (#6402 (comment))
pytest-django also uses it, which looks nice: https://pytest-django.readthedocs.io/en/latest/
(via pytest-dev/pytest-django@265a45f)

[AWhetter]

I don't like the pallets design as much as the current one. The font is less easy to read and there's a mix between serif and sans-serif fonts that doesn't look right to me. Sections and objects in the API reference are a bit more clearly defined and are easy to spot when scrolling through the page. The colour palette of code blocks is weird but they stand out and do the job. I much prefer the original code blocks.

[nicoddemus]

I'm OK with trying the "sphinx_rtd_theme" too, I kind of like it.

[blueyed]

I'm OK with trying the "sphinx_rtd_theme" too, I kind of like it.

Cool. Maybe in a parallel PR for comparison?

[nicoddemus]

Yeah, I also found another theme which I liked... let me try that as well.

[nicoddemus]

Pushed new branches, here's what we have for comparision:

• flask (Replace custom flask theme by the official one #6453)
• stanford
• rtd (Use rtd theme #6460)

[nicoddemus]

stanford is out of the picture because it seems it is not maintained anymore (#6459).

I will gladly accept suggestions of other themes btw.

[blueyed]

Should we have a vote then? I will add comments that can be voted up/down below.

[blueyed]

Please vote this comment up if you like the updated flask theme, and down if you are strongly opposed to it.
Preview: https://docs.pytest.org/en/use-standard-flask-theme (PR #6453).

[blueyed]

Please vote this comment up if you like the Sphinx ReadTheDocs theme, and down if you are strongly opposed to it.
Preview: https://docs.pytest.org/en/use-rtd-theme (PR #6460).

[The-Compiler]

I do like the RTD theme, but its sidebar seems quite messy compared to our current one - is this something we could port over to the RTD theme as well?

[nicoddemus]

I do like the RTD theme, but its sidebar seems quite messy compared to our current one - is this something we could port over to the RTD theme as well?

https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#how-the-table-of-contents-displays

Not sure how to configure it properly though... 🤔

[blueyed]

Let's move the RTD theme config related discussion to the theme's PR: #6460 (comment)

[nicoddemus]

So in the end we decided to ditch the customizations we had on the Flask theme and update it to the last official version (#6453).

Thanks everyone!