Repository navigation
Opinions: Looks of the pytest docs? #6402
Description
Activity
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?
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.
Reacted by Euber Alexandre BarbosaGiven 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. 👍
Many projects just use the RTD theme - and I think that's a great idea.
Reacted by Daniel Hahler and Alex PrengèreI 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.Reacted by Bruno OliveiraOK 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.
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?
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
No time at the moment to take this on, I'm afraid - lots of stuff on my plate currently 😉
- added a commit that references this issue
on Jan 14, 2020 I changed it just to take a look how it looks:
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)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.
7 remaining items
stanfordis out of the picture because it seems it is not maintained anymore (#6459).I will gladly accept suggestions of other themes btw.
Should we have a vote then? I will add comments that can be voted up/down below.
Reacted by Bruno OliveiraPlease 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).Reacted by Bruno OliveiraReacted by Ashley WhetterPlease 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).Reacted by Freya Bruhin and João Paulo Taylor Ienczak ZanetteI 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?
Reacted by João Paulo Taylor Ienczak ZanetteI 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?
Not sure how to configure it properly though... 🤔
Let's move the RTD theme config related discussion to the theme's PR: #6460 (comment)
- added a commit that references this issue
on May 30, 2020 - added a commit that references this issue
on Jun 1, 2020 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!
Reacted by João Paulo Taylor Ienczak Zanette and Ashley Whetter
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:
re.search,re.escape) have a nice highlight; in the first screenshot they are easy to miss in the middle of the text.[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?