Docs overhaul: GitHub Discussions, add logo, new theme #4960

JOJ0 · 2023-10-20T14:18:41Z

Description

Fixes #4916

Encourage users/devs to go to GitHub discussions instead of Discourse.
Add the beets logo.
~~Make sure the Alabaster theme stays used.~~
~~Some customization attempts to the Alabaster theme.~~
~~And some bad news.....read my post below.~~
New Sphinx theme "pydata" with some "beetrooty" customizations

To Do

Documentation
~~Changelog.~~
~~Tests.~~

Preview

JOJ0 · 2023-10-20T14:47:10Z

@sampsyo @RollingStar @Serene-Arc

The bad news is:

The Alabaster theme is not very mobile friendly. There is no "pull down / hamburger" menu implemented. It's almost impossible to navigate in the docs properly. (Yes I do very often read them on my mobile. It is a major concern to my personal use of it.)
Also on a desktop browser it is lacking proper sidebar navigation. It seems we are not allowed to dive deeper into the tree than the first 2 levels. For example check out the Configuration chapter and compare the two themes:
- https://beets.readthedocs.io/en/latest/reference/config.html#replace
- https://beets.readthedocs.io/en/v1.6.0/reference/config.html#replace
- The readthedocs theme has an option that controls how deep the tree expands: 'navigation_depth': 8,, I tried setting it for the alabaster theme options but it's ignored - just not supported. Again, especially on mobile, this is IMO an essential feature to navigate through such an extensive documentation without getting crazy with scrolling (also there usually is no "Ctrl + F" on mobile!

Out of the box Alabaster doesn't offer as much configuration abilities as readthedocs theme: https://alabaster.readthedocs.io/en/latest/customization.html#theme-options

It's suggested that custom_stylesheet is used for customization. So, if we continue to want to go down that route, I would greatly appreciate any input on where possible this CSS should be altered to adress my above mentioned concerns:

Some more resources to dig in, maybe I missed something, help me get through all that:

sampsyo

Awesome; thanks for changing all these links! I found one nit to fix.

It's too bad about the mobile usefulness of Alabaster. That doesn't seem great! I can see what you mean when browsing, for example, https://requests.readthedocs.io/ on mobile. It's fine-ish for reading the current page, but there is no navigation—the sidebar is just completely hidden on mobile.

Ah well. Maybe we should just go back to the RTD theme? Even if it's less beautiful, it is more full featured. I guess we could browse other Sphinx themes too, but it doesn't necessarily seem like the most effective use of time to worry too much about picking the perfect one:
https://sphinx-themes.org

README_kr.rst

@@ -104,5 +104,5 @@ Read More
 `Adrian Sampson`_ 와 많은 사람들의 지지를 받아 Beets를 만들었다.
 돕고 싶다면 `forum`_.를 방문하면 된다.

-.. _forum: https://discourse.beets.io
+.. _forum: https://https://github.com/beetbox/beets/discussions/


Serene-Arc · 2023-10-21T09:42:58Z

I vote for changing the theme if it's causing this much angst. The visual continuity is less important than the practical use, which is the point of documentation. We should just get a new theme and go with that. New theme right around the time of our only release for like two years wouldn't cause too much confusion either.

JOJ0 · 2023-10-21T11:41:19Z

@Serene-Arc forget my last two comments! I should read more carefully before replying 😅 I think we are on the same page here. Functionality should come first! That's why the Alabaster theme already has lost the race for me, even though I love it visually. So since yesterday evening I'm thinking about either going back to readthedocs (because we know it works!) or finding something new.

@sampsyo since you handed over "the mighty beetroot" to me, there was no going back! 🤣 Have a look below why we can't go back to the readthedocs theme haha!

JOJ0 · 2023-10-21T11:47:55Z

So I had a wonderful morning with playing around with Sphinx theming and (no shit) I really enjoyed it :-)

readthedocs with some customization - top left background defaulting to blue was a no-go with the beetroot with white background. There is issues though: The version number text is white, as well as the "beets" title on top of the logo. That would require more customization.

JOJ0 · 2023-10-21T11:53:32Z

This is the book theme. From scrolling thru all the themes yesterday evening this was my favorite and I thought it could be our best choice. I had to do some customization though since initially the font-size overall was too big for my taste. I really couldn't stand that, so now let me proudly present....base-font set a nuance smaller. I like it now. It's also mobile friendly they say. Please not the secondary sidebar on the right. It shows the current pages chapters in detail. Very handy to jump between let's say different config options (assuming we were in the Configuration chapter)! Great feature!

JOJ0 · 2023-10-21T12:02:54Z

After my first failed attempts getting my former favorite - the book theme - right, I learned that book is a close descendet of the pydata theme. So I gave this one a try and surprisingly I have to admit: This is my absolute favorite now! Even though it has loads of features, it still has a very clean look! Also dig the smaller logo on top left. Best feature is (next to the secondary sidebar we know from the book theme already) the "top level navigation" - it is super handy to have our main chapters on first sight, actually at all times, sitting there and switching between them is made so easy without having to use a sidebar at all.

So yeah, that would be my favorite! What do you guys say? @Serene-Arc @sampsyo @Steffo99 @RollingStar

(I have the setup of all those themes each in a single commit now so actually we could even give one a try and redecide later on - switching now is easy. To really test it for mobile purposes we have to actually merge it, I can't think of another easy way)

Steffo99 · 2023-10-21T12:04:53Z

Looks nice and intuitive!

sampsyo · 2023-10-21T19:58:51Z

Awesome!!! That PyData theme looks really good—it's less retro-looking than the official RTD theme, and the navigation features look useful. I say go for it!

and leave html_static_path commented out in conf.py as a reminder. We might need it if builds via readthedocs require it.

and rephrase a little if required. Often "our forums" was stated. Mostly I tried to use the wording "discussion board" throughout and (almost) never used the term "GitHub Discussions"

- Fixed sidebar - Sidebar collapse (default but make sure)

- Sticky Nnavigation (default but make sure) - Top left area white, to fit with beets logo background - Title "beets" - Logo only false, we want to see title - Version true, we want to see which beets version we are looking at - Issue: The latter two are invisible, would require custom CSS!!!

- Collapse nav - Add title "beets" next to small logo on top left

- Reduce base font a bit by custom.css - Collapse nav - Title "beets" below logo

This reverts commit 71873b6. Revert back to using "pydata" theme. Keep this in the history, just in case we reconsider to using "book".

Serene-Arc · 2023-10-23T07:55:50Z

I think it's great!

- Set static path and css file in Sphinx config. - Codebox style to black/white - Secondary color to beetroot red - Inline code color to beetroot green - Leave primary color (pydata teal), difficult to read with beetroot green. Works well with beetroot red actually. - Leave some notes on colors in beets.css for reference.

JOJ0 · 2023-10-23T10:43:53Z

@Serene-Arc or @sampsyo a little help required :-)

I can't get the test-docs job to run successfully. I've added the them package to the docs requirements in setup.py, but that doesn't seem to be enough. A local docs run tells me this:

$ tox -e docs
.pkg: _optional_hooks> python /Users/jojo/.pyenv/versions/beets310/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta __legacy__
.pkg: get_requires_for_build_sdist> python /Users/jojo/.pyenv/versions/beets310/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta __legacy__
.pkg: get_requires_for_build_wheel> python /Users/jojo/.pyenv/versions/beets310/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta __legacy__
.pkg: prepare_metadata_for_build_wheel> python /Users/jojo/.pyenv/versions/beets310/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta __legacy__
.pkg: build_sdist> python /Users/jojo/.pyenv/versions/beets310/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta __legacy__
docs: install_package> python -I -m pip install --force-reinstall --no-deps /Users/jojo/git/beets/.tox/.tmp/package/4/beets-1.6.1.tar.gz
docs: commands[0]> sphinx-build -W -q -b html docs /Users/jojo/git/beets/.tox/docs/tmp/html

Theme error:
no theme named 'pydata_sphinx_theme' found (missing theme.conf?)
docs: exit 2 (0.94 seconds) /Users/jojo/git/beets> sphinx-build -W -q -b html docs /Users/jojo/git/beets/.tox/docs/tmp/html pid=59710
.pkg: _exit> python /Users/jojo/.pyenv/versions/beets310/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta __legacy__
  docs: FAIL code 2 (11.44=setup[10.50]+cmd[0.94] seconds)
  evaluation failed :( (11.58 seconds)

do I need to add the theme name/package somewhere in ci.yaml workflow?

(I think the "missing theme.conf" error is misleading - at least up to my current research....)

Thanks in advance for any hints!

and in add to deps in tox.ini.

JOJ0 · 2023-10-23T11:27:56Z

Got it! Adding to tox.ini deps=... was missing. Sometimes reading docs of tools helps ;-)

JOJ0 · 2023-10-23T13:39:29Z

Oh wow! It's lovely on mobile as well. I'm very happy with it 😍

Two fixme's though: Forgot to set favicon to beetroot too! And I forgot to disable the "dark theme button" I mean we can keep it but I just didnt customize it to fit with the logo, so @sampsyo if you could send me the beetroot with a transparent background instead of white or the original project file, if it still exists. Or tell me to screw around with the pic I got with Gimp myself and I'll fix at least the logo for the darktheme :-))

For now all good I guess 😃

sampsyo · 2023-10-25T18:19:37Z

Wow; awesome that this worked out so well!!

I did find this transparent-background PNG lying around. I hope this fits the bill!

JOJ0 · 2023-10-29T09:44:41Z

Wow; awesome that this worked out so well!!

I did find this transparent-background PNG lying around. I hope this fits the bill!

Perfect! Thanks a lot! I quickly exchanged it in master d80d459

Now both light and dark theme use it.

I reconsidered about the favicon: The regular "readthedocs" favicon is being used and I think a lot of people are very used to finding python project docs with that typical favicon between all their open browser tabs (including myself), so I think that is actually a good thing.

So IMO, all sorted out here :-)

RollingStar · 2023-10-29T19:39:23Z

Thank you! Some examples with the new theme:

https://beets.readthedocs.io/en/latest/index.html

https://beets.readthedocs.io/en/latest/faq.html

https://beets.readthedocs.io/en/latest/team.html

JOJ0 force-pushed the docs_logo branch from d7b0c9f to 87076f5 Compare October 20, 2023 14:22

JOJ0 requested a review from jef October 20, 2023 14:25

JOJ0 self-assigned this Oct 20, 2023

JOJ0 requested review from sampsyo and Serene-Arc October 20, 2023 14:26

sampsyo reviewed Oct 20, 2023

View reviewed changes

JOJ0 force-pushed the docs_logo branch from 87076f5 to 49e649f Compare October 21, 2023 09:02

This comment was marked as off-topic.

Sign in to view

JOJ0 added 6 commits October 23, 2023 09:51

Add beets logo to docs

a6032cd

and leave html_static_path commented out in conf.py as a reminder. We might need it if builds via readthedocs require it.

Fix all occurences of Discourse to GH-Discussions

8260427

and rephrase a little if required. Often "our forums" was stated. Mostly I tried to use the wording "discussion board" throughout and (almost) never used the term "GitHub Discussions"

Set and configure Sphinx theme "alabaster"

9e972fe

- Fixed sidebar - Sidebar collapse (default but make sure)

Set and configure Sphinx theme "pydata"

957a6e4

- Collapse nav - Add title "beets" next to small logo on top left

Set and configure Sphinx theme book

71873b6

- Reduce base font a bit by custom.css - Collapse nav - Title "beets" below logo

JOJ0 force-pushed the docs_logo branch from 49e649f to 71873b6 Compare October 23, 2023 07:52

Revert "Set and configure Sphinx theme book"

4dc1f25

This reverts commit 71873b6. Revert back to using "pydata" theme. Keep this in the history, just in case we reconsider to using "book".

JOJ0 added 2 commits October 23, 2023 10:12

Rename assets/ to _static/ (logo, css, custom Sphinx stuff)

c1e2b34

JOJ0 changed the title ~~Docs overhaul - Suggest GH-Discussions, Add logo, Customize Alabaster~~ Docs overhaul: GitHub Discussions, add logo, new theme Oct 23, 2023

Replace Sphinx theme requirement in setup.py

df2b173

and in add to deps in tox.ini.

JOJ0 force-pushed the docs_logo branch from 8b1b764 to df2b173 Compare October 23, 2023 11:26

JOJ0 merged commit 894039d into beetbox:master Oct 23, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs overhaul: GitHub Discussions, add logo, new theme #4960

Docs overhaul: GitHub Discussions, add logo, new theme #4960

JOJ0 commented Oct 20, 2023 •

edited

Loading

JOJ0 commented Oct 20, 2023 •

edited

Loading

sampsyo left a comment

This comment was marked as resolved.

Serene-Arc commented Oct 21, 2023

This comment was marked as off-topic.

This comment was marked as off-topic.

JOJ0 commented Oct 21, 2023

JOJ0 commented Oct 21, 2023 •

edited

Loading

JOJ0 commented Oct 21, 2023 •

edited

Loading

JOJ0 commented Oct 21, 2023 •

edited

Loading

Steffo99 commented Oct 21, 2023

sampsyo commented Oct 21, 2023

Serene-Arc commented Oct 23, 2023

JOJ0 commented Oct 23, 2023 •

edited

Loading

JOJ0 commented Oct 23, 2023

JOJ0 commented Oct 23, 2023 •

edited

Loading

sampsyo commented Oct 25, 2023

JOJ0 commented Oct 29, 2023 •

edited

Loading

RollingStar commented Oct 29, 2023

Docs overhaul: GitHub Discussions, add logo, new theme #4960

Docs overhaul: GitHub Discussions, add logo, new theme #4960

Conversation

JOJ0 commented Oct 20, 2023 • edited Loading

Description

To Do

Preview

JOJ0 commented Oct 20, 2023 • edited Loading

sampsyo left a comment

Choose a reason for hiding this comment

This comment was marked as resolved.

Serene-Arc commented Oct 21, 2023

This comment was marked as off-topic.

This comment was marked as off-topic.

JOJ0 commented Oct 21, 2023

JOJ0 commented Oct 21, 2023 • edited Loading

JOJ0 commented Oct 21, 2023 • edited Loading

JOJ0 commented Oct 21, 2023 • edited Loading

Steffo99 commented Oct 21, 2023

sampsyo commented Oct 21, 2023

Serene-Arc commented Oct 23, 2023

JOJ0 commented Oct 23, 2023 • edited Loading

JOJ0 commented Oct 23, 2023

JOJ0 commented Oct 23, 2023 • edited Loading

sampsyo commented Oct 25, 2023

JOJ0 commented Oct 29, 2023 • edited Loading

RollingStar commented Oct 29, 2023

JOJ0 commented Oct 20, 2023 •

edited

Loading

JOJ0 commented Oct 20, 2023 •

edited

Loading

JOJ0 commented Oct 21, 2023 •

edited

Loading

JOJ0 commented Oct 21, 2023 •

edited

Loading

JOJ0 commented Oct 21, 2023 •

edited

Loading

JOJ0 commented Oct 23, 2023 •

edited

Loading

JOJ0 commented Oct 23, 2023 •

edited

Loading

JOJ0 commented Oct 29, 2023 •

edited

Loading