HTML theme configuration

Configuring the HTML theme

By default the HTML documentation will be built using the values already predefined in the theme.conf file, available with the downloaded theme. These default options can be customized by changing some variables in the conf.py file.

Configuring the document

The options for the HTML page can be set using the html_theme_optons variable. Edit the conf.py file and set the proper values for each option.

Setting the main color

The main color for the HTML documentation can be set in the html_theme_options variable using the option html_main_color.

html_theme_options = {
    ...
    'html_main_color' : '#0000AA',
    ...
}

Change the default hexadeciomal value ‘#0000AA’ (corresponding to a dark blue color) to the value for the main page color that you prefer.

Hint

You can use an online color picker to get the right hexadecimal value for any given color.

Setting the page width

The page width of the document including the body and the sidebar is set in the html_theme_options variable using the option html_page_width.

html_theme_options = {
    ...
    'html_page_width' : '1024px',
    ...
}

The values for the page width need to be valid HTML literals, like 1024 or the equivalent 1024px as well as 70%.

Setting the page margin

The page margin, before and after the document itself, is set in the html_theme_options variable with the option html_page_margin.

html_theme_options = {
  ...
  'html_page_margin' : '100px',
  ...
}

The values for the page margin need to be valid HTML literals, like 100 or the equivalent 100px as well as 15%.

Configuring the header

Setting the header text color

The header text color is set in the html_theme_options variable with the option html_theme_header_color.

html_theme_options = {
  ...
  'html_header_color' : 'white',
  ...
}

This is the main text color for the header, which uses the html_main_color as background. It is also the inheritated color for links in the header. For the text color of the title and subtitle see below.

Setting the header padding

The header internal padding space is set in the html_theme_options variable with the option html_theme_header_padding.

html_theme_options = {
  ...
  'html_header_padding' : '0px',
  ...
}

The values for the padding need to be valid HTML literals, like 5px or 5px 3px 3px 5px, as well as auto, 10%, etc.

Setting the header title

The header of each web page also contains a title text. To set the title text use the variable html_context to pass the value to the Sphinx engine:

html_context = {
    ...
    'html_header_title': 'My new project title',
    ...
}

If no entry html_header_title is given in the html_context, the name of the project, as defined in the project variable in the conf.py file will be used. Also, you can assign this variable or any other to this property:

html_context = {
    ...
    'html_header_title': project,
    ...
}

The title font color be changed from the header color using the html_theme_options array:

html_theme_options = {
  ...
  'html_header_title_font_color' : 'white',
  ...
}

The title font size be resized using the html_theme_options array:

html_theme_options = {
  ...
  'html_header_title_font_size' : '1em',
  ...
}

The values for this property need to be valid HTML literals, like 15px or 1.2em.

Setting the header subtitle

Below the header title, an acompanying subtitle can be provided in the variable html_context:

html_context = {
    ...
    'html_header_subtitle': 'This is my brand, new project!',
    ...
}

If no entry html_header_subtitle is given in the html_context no subtitle is displayed, only the main title.

The subtitle font color be changed from the header color using the html_theme_options array:

html_theme_options = {
  ...
  'html_header_subtitle_font_color' : 'white',
  ...
}

The subtitle font size be resized using the html_theme_options array:

html_theme_options = {
  ...
  'html_header_subtitle_font_size' : '1em',
  ...
}

The values for this property need to be valid HTML literals, like 10px or 0.8em.

Configuring the superheader

The superheader is an area above the header than can be redefined for your own purposes in the layout.html file.

Setting the superheader padding

The superheader internal padding space is set in the html_theme_options variable with the option html_theme_superheader_padding.

html_theme_options = {
  ...
  'html_superheader_padding' : '5px',
  ...
}

The values for the padding need to be valid HTML literals, like 5px or 5px 3px 3px 5px.

Configuring the subheader

The subheader is an area below the header than can be redefined for your own purposes in the layout.html file.

Setting the subheader padding

The subheader internal padding space is set in the html_theme_options variable with the option html_theme_subheader_padding.

html_theme_options = {
  ...
  'html_subheader_padding' : '5px',
  ...
}

The values for the padding need to be valid HTML literals, like 5px or 5px 3px 3px 5px.

Configuring the superfooter

The superfooter is an area above the footer than can be redefined for your own purposes in the layout.html file.

Setting the superfooter padding

The superfooter internal padding space is set in the html_theme_options variable with the option html_theme_superfooter_padding.

html_theme_options = {
  ...
  'html_superfooter_padding' : '5px',
  ...
}

The values for the padding need to be valid HTML literals, like 5px or 5px 3px 3px 5px.

Configuring the subfooter

The subfooter is an area below the footer than can be redefined for your own purposes in the layout.html file.

Setting the subfooter padding

The subfooter internal padding space is set in the html_theme_options variable with the option html_theme_subfooter_padding.

html_theme_options = {
  ...
  'html_subfooter_padding' : '5px',
  ...
}

The values for the padding need to be valid HTML literals, like 5px or 5px 3px 3px 5px.

Configuring the HTML website

Additional properties of the final, generated HTML pages can be set using some html_* variables. Edit the conf.py file and set the corresponding variables with the proper values.

Setting the HTML title

As HTML pages, each generated documentation page can show a page title in the web browser’s window top bar.

To set this title, use the variable html_title in the conf.py file.

html_title = 'Documentation Website'

Tip

You do not need to set this variable. Sphinx will generate a title from the project variable and version. Use this feature to change the default behaviour.

Setting the favicon

As a HTML website, the generated documentation can include a favorite icon or favicon to be shown by web browsers supporting this feature.

To set this option, save an icon image file in the _static directory and point the html_favicon variable to this file.

html_favicon = '_static/favicon.png'

Tip

You do not need to set this variable when only building PDF documentation. Indeed, you do not need this feature to build HTML documentation either.