Edit the Sphinx Alabaster jinja template - python-sphinx

Question

As an educational exercise, I would like to build upon the default Spinx theme Alabaster and add additional features by making changes in the jinja template.
Thus, I set up a virtual environment, installed Sphinx, copied the Alabaster folder to my working folder, _themes/Alabaster2, updated conf.py, and compiled an HTML project. This approach resulted in several missing dependencies. For example, not even the "basic" theme to be inherited could be found! None of the html_theme_options set in the conf.py file worked.
How can I overcome these shortcomings, i.e. have a working copy of Alabaster in my working folder and make changes to the jinja template?
If anyone with experience of developing themes for the Sphinx documentation system could shed some light on how to setup a environment where it is possible to tweak the templates used by Alabaster it would be most appreciated!
Additional details on my (failed) approach
Working on Windows 10, the project is set up by executing the following commands in the terminal
python -m venv .venv
.venv\scripts\activate
python -m pip install sphinx
sphinx-quickstart site #I opted for different source and build folders
cd site
mkdir _themes
xcopy ..\.venv\Lib\site-packages\alabaster _themes\alabaster2\ /E
I updated the HTML output section in source\conf.py
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme_path = ["_themes"]
html_theme = 'alabaster2'
html_theme_options = {
'logo': 'logo.png',
'description':'Welcome to MySite',
'description_font_style':'Monospace',
'fixed_sidebar':True,
'logo_name':False,
'logo_text_align':None,
'page_width':'90%',
'sidebar_width':'280px',
# 'analytics_id':'UA-#######-##',
#'donate_url':'www.paypal.com',
# 'extra_nav_links':True,
'show_related':False,
'show_relbars':True,
'sidebar_collapse':True,
'show_powered_by':True,
}
And then in the terminal
make html
The generated build\html\index.html file does not work as expected, for example, none of the options set in the dictionary html_theme_options located in conf.py are taken in consideration.
Software versions
(.venv) >python --version
Python 3.8.8
(.venv) >sphinx-build --version
sphinx-build 4.2.0

Answer 1

After reading the documentation (!) I concluded that I'm going about this the wrong way, i.e. "to build upon the default Spinx theme Alabaster" you don't need to edit the Jinja templates!
For example, say you want to add the following functionalities to the default Sphinx Alabaster theme:
CSS to center align images
javascript for cookie consent
Import Bootstrap CSS
Include a logo image
In this post I will answer and comment on my own question, and show how the result illustrate below can be fairly easy achieved, with minimum coding.
Default installation on Windows 10
python -m venv .venv
.venv\scripts\activate
python -m pip install sphinx
sphinx-quickstart site #I opted for different source and build folders
cd site
Update source/conf.py
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
html_title = 'SOLUTION'
# Custom css files
html_css_files = [
'css/custom.css',
]
html_theme_options ={
'logo':'img/logo.png',
'description':'Washing machines works better with software',
'description_font_style':'Monospace',
'fixed_sidebar':True,
'logo_name':False,
'logo_text_align':None,
'page_width':'75%',
'sidebar_width':'250px',
# 'analytics_id':'UA-#######-##',
#'donate_url':'www.paypal.com',
# 'extra_nav_links':True,
'show_related':False,
'show_relbars':True,
'sidebar_collapse':True,
'show_powered_by':True,
}
Add custom css and html
Add source/_static/css/custom.css hosting the .centeralign class.
.centeralign {
display: block;
margin-left: auto;
margin-right: auto;
width: 50%;
margin-top: 40px;
margin-bottom: 30px;
}
Add a logo image to source/_static/img/logo.png
Add source\_templates\layout.html with the content listed below
{% extends "!layout.html" %}
{% block extrahead %}
{{ super() }}
<!-- Code for cookie consent -->
<script></script>
{% endblock %}
{% block linktags %}
<link href="https://cdn.jsdelivr.net/npm/bootstrap#5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
{% endblock %}
source/index.rst
Add the following code to index.rst
.. DUST documentation master file, created by
sphinx-quickstart on Tue Oct 26 08:47:02 2021.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to DUSTS's documentation!
=================================
Insert an image and style with Bootstrap classes.
.. code-block:: reStructuredText
.. image:: _static/img/abstract-g90ed47336_1280.jpg
:alt: DUST washing cloud
:class: img-fluid, rounded, mx-auto, d-block, shadow-sm, my-3
.. image:: _static/img/abstract-g90ed47336_1280.jpg
:alt: DUST washing cloud
:class: img-fluid, rounded, mx-auto, d-block, shadow-sm, my-3
Image by `Tomislav Jakupec <https://pixabay.com/users/tommyvideo-3092371/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=5719221>`_ from `Pixabay <https://pixabay.com/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=5719221>`_.
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
The image used in the example
Image by Tomislav Jakupec from Pixabay
Make html
In the terminal execute make html and open the file build/html/index.html