From 365c1c348457e5f076cbc0109c2710ece754e510 Mon Sep 17 00:00:00 2001 From: Sunil Mohan Adapa Date: Mon, 23 Feb 2026 13:35:08 -0800 Subject: [PATCH] doc/dev: Set new theme for developer documentation - Change theme to 'Book' based on Sphinx pydata theme. It supports dark/light modes. Looks more modern and better defaults/options. - Add logo on the top left corner. - Add menu to go to repository, view page source, edit page source, and report issue on current page. - Don't repeat 'FreedomBox Authors' in authors text and copyright text. Show only once as suggested by the theme. - Use theme option to show license link instead of overriding the template. Tests: - After building the theme, all options work as expected. - Footer appears as expected. Signed-off-by: Sunil Mohan Adapa --- doc/dev/README.rst | 1 + doc/dev/_static/logo.svg | 122 +++++++++++++++++++++++++++++++++ doc/dev/_templates/layout.html | 15 ---- doc/dev/conf.py | 20 ++++-- 4 files changed, 137 insertions(+), 21 deletions(-) create mode 100644 doc/dev/_static/logo.svg delete mode 100644 doc/dev/_templates/layout.html diff --git a/doc/dev/README.rst b/doc/dev/README.rst index 66612209f..ced4e7295 100644 --- a/doc/dev/README.rst +++ b/doc/dev/README.rst @@ -19,6 +19,7 @@ Install the following Debian packages: * python3-sphinx * python3-sphinx-autobuild +* python3-sphinx-book-theme * python3-django * python3-django-axes * python3-django-captcha diff --git a/doc/dev/_static/logo.svg b/doc/dev/_static/logo.svg new file mode 100644 index 000000000..b51a72ede --- /dev/null +++ b/doc/dev/_static/logo.svg @@ -0,0 +1,122 @@ + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/doc/dev/_templates/layout.html b/doc/dev/_templates/layout.html deleted file mode 100644 index aa02582ec..000000000 --- a/doc/dev/_templates/layout.html +++ /dev/null @@ -1,15 +0,0 @@ -{%- extends "alabaster/layout.html" %} - -{%- block footer %} -
- {% if show_copyright %}©{{ copyright }} | {% endif %} - Licensed under the - CC BY-SA 4.0 license - {%- if show_source and has_source and sourcename %} - {% if show_copyright or theme_show_powered_by %}|{% endif %} - {{ _('Page source') }} - {%- endif %} -
- -{% endblock %} diff --git a/doc/dev/conf.py b/doc/dev/conf.py index dfb88f625..a32dd2fe8 100644 --- a/doc/dev/conf.py +++ b/doc/dev/conf.py @@ -15,11 +15,10 @@ list see the documentation: http://www.sphinx-doc.org/en/master/config # import os import sys +from datetime import datetime import django -from datetime import datetime - sys.path.insert(0, os.path.abspath('../../')) os.environ['DJANGO_SETTINGS_MODULE'] = 'plinth.settings' django.setup() @@ -28,7 +27,7 @@ django.setup() # pylint: disable=invalid-name project = 'FreedomBox' -copyright = f'2021-{datetime.now().year}, FreedomBox Authors' +copyright = f'2021-{datetime.now().year}' author = 'FreedomBox Authors' # The short X.Y version @@ -84,15 +83,23 @@ pygments_style = None # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'sphinx_book_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # html_theme_options = { - 'fixed_sidebar': True, - 'show_related': True, + 'home_page_in_toc': True, + 'repository_provider': 'gitlab', + 'repository_url': 'https://salsa.debian.org/freedombox-team/freedombox/', + 'use_edit_page_button': True, + 'use_source_button': True, + 'use_repository_button': True, + 'use_issues_button': True, + 'path_to_docs': 'doc/dev/', + 'extra_footer': 'Licensed under the CC BY-SA 4.0 license.', } # Add any paths that contain custom static files (such as style sheets) here, @@ -223,3 +230,4 @@ autodoc_mock_imports = [ ] html_favicon = './_static/favicon.ico' +html_logo = './_static/logo.svg'