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 <sunil@medhas.org>

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

doc/dev/_templates/layout.html

@@ -1,15 +0,0 @@
-{%- extends "alabaster/layout.html" %}
-
-{%- block footer %}
-  <div class="footer">
-    {% if show_copyright %}&copy;{{ copyright }} | {% endif %}
-    Licensed under the <a href="https://creativecommons.org/licenses/by-sa/4.0/">
-    CC BY-SA 4.0</a> license
-    {%- if show_source and has_source and sourcename %}
-      {% if show_copyright or theme_show_powered_by %}|{% endif %}
-      <a href="{{ pathto('_sources/' + sourcename, true)|e }}"
-         rel="nofollow">{{ _('Page source') }}</a>
-    {%- endif %}
-  </div>
-
-{% endblock %}

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,
+    'home_page_in_toc': True,
-    'show_related': 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 <a href="https://creativecommons.org/'
+                    'licenses/by-sa/4.0/">CC BY-SA 4.0</a> 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'