search

randombit / botan

Cryptography Toolkit
https://botan.randombit.net
BSD 2-Clause "Simplified" License
2.49k stars 553 forks source link

Proposal: Use furo theme for Sphinx docs #3818

Open securitykernel opened 7 months ago

securitykernel commented 7 months ago

We currently use the readthedocs theme for publishing documentation on https://botan.randombit.net with Sphinx.

I recently discovered the furo theme for Sphinx, which is used by pip, python-gitlab, urllib3 and more. IMHO it looks much cleaner than readthedocs, and optionally allows the user to switch to dark mode. Below are some screenshots for comparison. I also uploaded a full recent Botan docs made with furo to https://docs.botan-crypto.org/furo/ to browse.

Start page

image image

Building The Library

image image

Random Number Generators

image image

TLS Code Example

image image

What do you think?

randombit commented 7 months ago

No objection here

mouse07410 commented 7 months ago

Does this add a dependency and require installing an extra Sphinx theme furo?

If so, shouldn't building.md tell that it's necessary for docs target, and how to install it?

securitykernel commented 7 months ago

It is not required. Just like before with the readthedocs theme, it will fall back to the agogo theme shipped with Sphinx automatically if furo is not found.

lieser commented 4 months ago

@randombit I would love it if the official Botan website could switch to this theme. Currently it is only used as the default in the build scripts (if available), but not on the official site.

I think long sites like e.g. https://botan.randombit.net/handbook/api_ref/pubkey.html would benefit a lot of the better navigation via the sidebar that duro provides compared to the theme currently used.