Fix Sphinx configuration post-update

[snejus]

Adjust Sphinx configuration and release script

Changes:

• Update source_suffix in docs/conf.py to use dict format as required by newer Sphinx
  versions
• Fix typo in theme config: pygment_light_style -> pygments_light_style
• Improve release script to handle Sphinx intersphinx output formatting:
  • Replace tabs with spaces for consistent parsing
  • Add reference to sphinx.ext.intersphinx command in docstring
  • Update line parsing to match space-indented format
• Restructure CI workflow to ensure relevant dependencies are installed and changelog formatting is tested.

These changes ensure compatibility with newer Sphinx versions and improve the robustness
of the release script's reference parsing.

Edit:

While working on this PR GitHub decided to upgrade their linux/ubuntu runners with Ubuntu 24.04. Ubuntu upgrades are the worst: imagine not updating your system for 3 years and then suddenly upgrading everything to the most recent versions. At which point you start realizing that the final S in their LTS means Suffering instead of Support.

We use just a few system dependencies in our builds and as expected, things broke:

• libcairo2-dev now needs to be installed for pygobject.
• pandoc rst -> markdown conversion output has changed
• Completion tests are unhappy about bash / bash-completion upgrade, and I could not figure out why so I'm just xfailing that test in CI.

[github-actions]

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

[JOJ0]

I looked through it and most LGTM as you can read in inline comments. I'm wondering how I could simulate a release in my fork and see what the final outcome is. Is it as easy as pushing a tag to the fork and then do whatever is to do the trigger the workflow (need to read docs how to do the latter)

Fun fact: I copied the output of "releasy.py changelog" to a github release and the preview showed actual bug emojies for :bug: - a feature not a bug! sweet! 🍭 (and now realize that this is in place since a couple of releases already haha ;-))

Anyway I think this is already good to go and let's kick out more releases soon for the real test.

[JOJ0]

Whoops that typo was me. The funny thing is that we already seem to have the "black & white" style. If this is set to as you suggest, I get "colored" code boxes.

The pydata theme docs reveal that this was actually already set correctly and intentionally the "bw" theme was chosen (by me alone AFAIR - let's discuss if we want more color :-)). The colors we see when setting to "pygmentS..." is just the fallback to the default theme.

https://pydata-sphinx-theme.readthedocs.io/en/v0.14.4/user_guide/styling.html#configure-pygments-theme

[JOJ0]

Suggested change

	"pygments_light_style": "bw",
	"pygment_light_style": "bw",

[snejus]

The reason I adjusted it was this warning:

$ poe docs
Poe => make -C docs html
make: Entering directory '/home/sarunas/repo/beets/docs'
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v7.4.7
loading translations [en]... done
loading pickled environment... done
The parameter "pygment_light_style" was renamed to "pygments_light_style" (note the "s" on "pygments").
building [mo]: targets for 0 po files that are out of date

Have you poetry install before regenerating the docs?

[snejus]

On the other hand I've been a bit confused about the lack of colors! 😅 Would you mind if we remove this configuration, going back to the default?

[JOJ0]

Not that I have such a distro around but would it help to test it on a "real" Ubuntu install?

[JOJ0]

@snejus I think I found the cause. Debian/Ubuntu changed the path of bash. It's now /usr/bin/bash: https://launchpadlibrarian.net/715612409/bash_5.2.21-2ubuntu1_5.2.21-2ubuntu2.diff.gz

https://launchpad.net/ubuntu/+source/bash/5.2.21-2ubuntu2

Maybe we can try working around that by using /usr/bin/env bash?

[JOJ0]

....but I'm not sure anymore if my assumption is correct, let's simply trial and error is my best idea. Too much to read here in this "decision paper" (or whatever it is): https://dep-team.pages.debian.net/deps/dep17/

[JOJ0]

I played around with this in my open PR. Neither changing to /usr/bin/env bash nor changing to /usr/bin/bash fixes it. I'm sorry, it's something else :-(

And also I realize that we had a check for that in place already :-(

        if not has_program(cmd[0]):
            self.skipTest("bash not available")

[JOJ0]

After endless tinkering with getting bash-completion even to test on my laptop (macOS, old bash, incompatible completion script, yadda yadda) and wanting to debug it locally, I gave up on that idea and continued to push weird ideas to github. The first interesting clue: Permission denied !?!

[snejus]

😞 I see a familiar struggle here to what I experienced. I didn't manage to get as far as to trigger the permission denied error - this looks interesting. How did you do it?

[JOJ0]

I invested quite some time already trying to fix/understand the bash-completion issue. I suggest we keep it disabled as you suggested in commit 3bb8af8. It's not worth further hassle in my opinion!

Am I right that we have some of the issues you mention after the runner ubuntu upgade in all open PR's? If so, that's even more a reason to live with the bash-completion issue and move on with merging this one. It's good to go in my opinion. Thanks!

[snejus]

Am I right that we have some of the issues you mention after the runner ubuntu upgade

Yes, completely. Just let me know what do you think regarding removing the "bw" colors configuration to introduce coloring to the code blocks and we go ahead with the merge!