CI: Add python3-furo package for documentation build

[KaganCanSit]

Hello,

This PR was created to fix mobile-responsive layout issues on the documentation website by ensuring the furo Sphinx theme is installed during CI documentation builds. (Issue: #5243)

Note: I have limited experience in this area and received AI assistance during the investigation. While everything appears to work correctly, I would appreciate your review.

Investigation

First, I checked the issue on Brave, Edge and Firefox browsers using the provided link and confirmed that the problem occurs specifically in Firefox. Then I performed local build operations with Sphinx and conducted testing.

Initial Local Build

cd ~/Desktop/Projects/botan
python3 -m venv venv_test
source venv_test/bin/activate
pip install sphinx docutils  # Based on gha_linux_packages.py
make clean 2>/dev/null || true
rm -rf build/
./configure.py --with-sphinx
make docs 2>&1 | tee docs_build.log

The following warning message during documentation compilation caught my attention:

(venv) kagancansit@kagancansit:~/Desktop/Projects/botan$ make docs
"/home/kagancansit/Desktop/Projects/botan/venv/bin/python3" "src/scripts/build_docs.py" --build-dir="build"
INFO: sphinx-build -q -c ./src/configs/sphinx -j auto -W --keep-going -b html ./doc build/docs/handbook
Furo theme could not be imported; falling back to agogo
INFO: rst2man build/botan.rst build/botan.1

Local Build After Adding Furo

deactivate
rm -rf venv venv_test
python3 -m venv venv_test
source venv_test/bin/activate
pip install sphinx docutils furo
make clean 2>/dev/null || true
rm -rf build/
./configure.py --with-sphinx
make docs 2>&1 | tee docs_build.log

The warning is gone. The site's dark mode capability has been activate and the mobile responsive problem has been resolved.

Root Cause

The theme fallback occurs due to this logic in src/configs/sphinx/conf.py:

try:
    html_theme = "furo"
    html_theme_options = { ... }
except:
    print("Could not import furo theme; falling back to agogo")
    html_theme = 'agogo'

Without python3-furo installed in CI, the build falls back to agogo theme which lacks mobile responsive support.

Screenshots

Here are screenshots of the furo theme in Mobile and Desktop mode:

---

This change might not be the ideal solution, but I believe it aligns with the intended configuration. I also appreciate the furo theme's dark mode support and clean structure.

Sincerely.

[KaganCanSit]

Fist I change src/scripts/ci/gha_linux_packages.py file and add packages.append('python3-furo') but Ubuntu 22.04 not have a furo. I update src/scripts/ci/setup_gh_actions.sh.

[coveralls]

coverage: 90.399% (-1.5%) from 91.944%
when pulling 2c36c6e on KaganCanSit:fix-docs-mobile-responsive
into 18cd21e on randombit:master.

[reneme]

Fist I changed src/scripts/ci/gha_linux_packages.py file and added packages.append('python3-furo') but Ubuntu 22.04 not have a furo. I update src/scripts/ci/setup_gh_actions.sh.

The "docs" CI job runs on Ubuntu 24.04 and there is a "furo" package (without python3 prefix). That should work.

$> apt search furo
Sorting... Done
Full Text Search... Done
furo/noble 2024.01.29+dfsg-1 all
  clean customisable Sphinx documentation theme

[KaganCanSit]

Fist I changed src/scripts/ci/gha_linux_packages.py file and added packages.append('python3-furo') but Ubuntu 22.04 not have a furo. I update src/scripts/ci/setup_gh_actions.sh.

The "docs" CI job runs on Ubuntu 24.04 and there is a "furo" package (without python3 prefix). That should work.

$> apt search furo
Sorting... Done
Full Text Search... Done
furo/noble 2024.01.29+dfsg-1 all
  clean customisable Sphinx documentation theme

Thanks, I had tried it as python3-furo. Honestly, the presence of the python prefix in sphinx probably led me to think that way. I'll try it now.

[reneme]

I had tried it as python3-furo. Honestly, the presence of the python prefix in sphinx probably led me to think that way. I'll try it now.

... strange naming of packages indeed. Change looks good now, thanks.

Though, I'm not sure that this CI build result is the artifact that @randombit is typically deploying straight to botan.randombit.net, so this may or may not address #5243.

[KaganCanSit]

I had tried it as python3-furo. Honestly, the presence of the python prefix in sphinx probably led me to think that way. I'll try it now.

... strange naming of packages indeed. Change looks good now, thanks.

Though, I'm not sure that this CI build result is the artifact that @randombit is typically deploying straight to botan.randombit.net, so this may or may not address #5243.

I understand. During development, I considered the possibility that the website was published from this repository on the botan.randombit.net domain using GitHub's Static Pages feature. However, even if that's not the case, I can assist if additional support/development is needed.

Thanks for the quick review and guidance.