Skip to content

Docs Visual Overhaul #2841

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

Merged
merged 10 commits into from
Jan 10, 2022
Merged

Docs Visual Overhaul #2841

merged 10 commits into from
Jan 10, 2022

Conversation

harshil21
Copy link
Member

@harshil21 harshil21 commented Jan 3, 2022

Visual changes:

  • Switch to furo theme.

Code changes:

  • Use parallelization to speed up sphinx build times.
  • Bump sphinx to 4.3.2

Other changes:

  • Use a table to represent bot methods in a compact manner.
  • Some doc fixes in jobqueue.py

@harshil21 harshil21 added enhancement ⚙️ documentation affected functionality: documentation labels Jan 3, 2022
@harshil21 harshil21 added this to the v14 milestone Jan 3, 2022
Copy link
Member

@Bibo-Joshi Bibo-Joshi left a comment

Choose a reason for hiding this comment

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

  • Color of border buttons are now more subtle and don't 'stand out' that much.
  • Fixes the white line on the sidebar border

these are really nice, good idea 👍

  • The top white separator line at the beginning of each page was made the same color as background.

Mh, the line is also there in the light theme - maybe just make it a bit more subtle?

  • Example box is now a bit rounded to look a bit modern.

I'd prefer to keep this as is, since the boxes arent't changed on the light theme and bc IMHO it doesn't really fit with the rest of the theme …

@harshil21
Copy link
Member Author

harshil21 commented Jan 4, 2022

Mh, the line is also there in the light theme - maybe just make it a bit more subtle?

👍🏼

I'd prefer to keep this as is, since the boxes arent't changed on the light theme and bc IMHO it doesn't really fit with the rest of the theme …

Maybe its time to update the light theme too? We can also make the boxes like warnings, notes, etc (slightly) 'rounded'.

I'll also think about adding a toggle to switch between light and dark mode

@Poolitzer
Copy link
Member

There are cool ways to do toggles without JS, I researched that a while ago. E.g. https://daveyhert.hashnode.dev/how-to-create-animated-toggle-switches-with-just-css-and-implement-a-dark-mode-feature

@Bibo-Joshi
Copy link
Member

Maybe its time to update the light theme too? We can also make the boxes like warnings, notes, etc (slightly) 'rounded'.

IMO this should then also cover the boxes for reference links, inline monospace text attribute/method names and so on. Personally, I'm fine with the non-round boxes … Ofc if you enjoy fiddling with CSS, I won't be the buzzkill :) However, it's probably worth to first look around for already existing sphinx themes that you/we like better than the current one.

There are cool ways to do toggles without JS, I researched that a while ago. E.g. https://daveyhert.hashnode.dev/how-to-create-animated-toggle-switches-with-just-css-and-implement-a-dark-mode-feature

should have expected you to say something like that 😄 AFAIK removing JS just for the sake of it isn't always the right thing to do, though

@harshil21 harshil21 mentioned this pull request Jan 7, 2022
4 tasks
@Bibo-Joshi
Copy link
Member

How about furo? even comes with a dropdown thingy that could be used for the bot methods table

@harshil21
Copy link
Member Author

How about furo? even comes with a dropdown thingy that could be used for the bot methods table

Wow, looks great! Even has a built in theme switcher!
Couldn't find the dropdown thing you were mentioning in their docs though

Copy link
Member

@harshil21 https://pradyunsg.me/furo/kitchen-sink/sphinx-design/

Furo basically comes with some 3rd party dep for that

@harshil21 harshil21 changed the title Improve dark mode contrast Docs Visual Overhaul Jan 8, 2022
@harshil21
Copy link
Member Author

Would be nice to build docs for this branch to test the new theme on mobile

Copy link
Member

@Bibo-Joshi Bibo-Joshi left a comment

Choose a reason for hiding this comment

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

Noice! Left some nitpicks. Build is up at https://python-telegram-bot.readthedocs.io/en/dark-mode-adjust/

Copy link
Member

@Bibo-Joshi Bibo-Joshi left a comment

Choose a reason for hiding this comment

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

Nice addition! LGTM. @Poolitzer do you want to have a look before we merge?

Copy link
Member

@Bibo-Joshi yes, today or tomorrow

@Poolitzer
Copy link
Member

words can't express how much I love that overhaul, amazing job.

Do we need an auto switch though in the dark light button? Can't we just have it set the proper auto theme, and then users can manually set it to the other if they want?

@harshil21
Copy link
Member Author

Do we need an auto switch though in the dark light button? Can't we just have it set the proper auto theme, and then users can manually set it to the other if they want?

but the point of the auto theme is that it switches automatically when light/dark mode is enabled?

Copy link
Member

@harshil21 But why? Are you constantly switching your browsers theme preferences while visiting a website?

@Bibo-Joshi Bibo-Joshi merged commit d4a2e40 into doc-fixes Jan 10, 2022
@Bibo-Joshi Bibo-Joshi deleted the dark-mode-adjust branch January 10, 2022 17:10
@harshil21 harshil21 restored the dark-mode-adjust branch January 10, 2022 17:12
@harshil21

This comment has been minimized.

@harshil21 harshil21 deleted the dark-mode-adjust branch January 10, 2022 17:16
@github-actions github-actions bot locked and limited conversation to collaborators Jan 17, 2022
@Bibo-Joshi Bibo-Joshi added 🔌 enhancement pr description: enhancement and removed enhancement labels Nov 3, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
⚙️ documentation affected functionality: documentation 🔌 enhancement pr description: enhancement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants