Switch to furo sphinx docs theme

[martinhoyer]

The currently used theme is not being updated and it's dependencies are causing issues, like #3087

This is a proof of concept of using the Furo theme, which is being used, among others, by pip, Python Developer’s Guide and black.

https://github.com/pradyunsg/furo
https://pradyunsg.me/furo/

Removing usage of rst2man and relying on sphinx builder to create manpage. This would be also a good opportunity to improve the man page, perhaps with additional pages and such.

We could also introduce sphinx-design, for which furo is the showpiece theme:https://sphinx-design.readthedocs.io/en/furo-theme/

Having markdown support would be a boon as well: https://myst-parser.readthedocs.io/en/latest/

Perhaps we could add https://github.com/executablebooks/sphinx-copybutton

Pull Request Checklist

• implement the feature
• write the documentation

[LecrisUT]

How about adding these to the sphinx setup or the Makefile?

tmt/docs/conf.py

Lines 316 to 327 in a08a4be

	def generate_tmt_docs(app: Sphinx, config: Any) -> None:
	""" Run `make generate` to populate the auto-generated sources """
	conf_dir = Path(app.confdir)
	subprocess.run(["make", "generate"], cwd=conf_dir, check=True)
	def setup(app: Sphinx) -> None:
	# Generate sources after loading configuration. That should build
	# everything, including the logo, before Sphinx starts checking
	# whether all input files exist.
	app.connect("config-inited", generate_tmt_docs)

Probably combining exclude_patterns = [r"man/*"] and manpages would work. I don't see config options for specific builder overrides.

[martinhoyer]

sure, whatever works. This is just a PoC of rendering the manpage in the same way as the current setup, just without rst2man.

[psss]

I like the current documentation theme and I'd probably suggest not to change the look that often. We've switched to renku in #2464 which is last November, so less than year. Unless there are a real blockers in further improvements (like the man page rendering) I would stick with renku at least for a while. Saying all this, the proposed furo theme does not look bad either.

[martinhoyer]

@psss I'm sure it can be configured to look/feel a bit more like the current theme, if it's about aesthetics.

Unless there are a real blockers in further improvements

I mean, we're already forced to use specific versions of packages, only a matter of time until something breaks again. Let alone being able to take advantage of development in newer sphinx versions, etc.

[LecrisUT]

From experience, themes can lag behind sphinx backend. I had issues on the book-theme needing to update a whole chain. furo I know it's well maintained, and I think renku would be good too

[martinhoyer]

I think renku would be good too

Looking at the repo activity...I'm not sure about that.

[LecrisUT]

For me furo already automatically enables dark mode for example on: https://scikit-build-core.readthedocs.io/en/latest/. I have it enabled system wide on the desktop (and firefox by proxy I guess)

[martinhoyer]

From the documentation, it's light by default, but switches to dark automatically when browser is set to prefer dark.

[LecrisUT]

Welp, no reason to complicate things. When I've had an epaper device, the dark-theme sites were unreadable, so in some edge cases it's better to let the system/browser set what it prefers, and let the users set it up or buy a good pair of sunglasses.

[martinhoyer]

Yep, agree, I'm just playing with it while in Draft. Also not happy with introducing js :)