How to modify Sphinx theme?#
Tech writers should write. Delivering documentation in a visually appealing manner is almost the same important as the content itself, however. Sphinx themes are “skins” that define look & feel of documentation when outputted to HTML format. In this post, you will learn how to customize existing or create a new theme from scratch.
Creating or customizing Sphinx theme requires at least basic web design skills and an understanding of how Sphinx theme works. The latter you will learn in here.
Custom CSS#
Custom CSS stylesheet is the most common way how to modify the existing Sphinx theme.
You will create custom CSS that will be placed as <link rel="stylesheet">
after theme’s main CSS giving you the opportunity to overwrite styles you don’t like.
Open your conf.py and search for
html_static_path
option. This option is the list of paths to folders and files that will be copied during the build to the output. There are big changes it will contains at least or only the_static
folder (html_static_path = ['_static']
). If not, append_static
to the option. Ensure this folder actually exist (at the level of conf.py file). For example:_static/ _templates/ getting-started/ installation/ theming/ conf.py index.rst second.rst third.rst
Still in conf.py: create or update the
html_css_files
option to containcustom.css
. For example:html_css_files = ["custom.css"]
Create
custom.css
inside_static/
folder. (You can choose whatever filename you like.)Write your custom styles or override existing. For example:
@import "https://fonts.googleapis.com/css?family=Saira+Extra+Condensed:700&subset=latin-ext"; h1, h2, h3, h4, h5, h6 { margin-top: 0; font-weight: 700; font-family: "Saira Extra Condensed", Arial, sans-serif; } h1, h2, h3 { text-transform: uppercase; } /* ... */
Delete output folder (usually
build
,_build
, etc.), build Sphinx project, open and check generated HTML files.
Modify favicon#
Favicons are small icons displayed on the page tab in the browser. Setting custom favicon is a must customization that is very easy to follow.
Put your favicon (probably named
favicon.ico
) to_static
folder.Set value of conf.py
html_favicon
option to path to this file. E.g.:html_favicon = "_static/favicon.ico"
Explore theme options#
Themes often has a collection of theme options <themes-options>
for fine-tuning the theme features. Theme options are usually used for setting font family, hiding logo, hiding prev/next buttons, etc. Have a look at your theme documentation what options you can modify.
Advantage of theme options is they are easy customizable in project’s conf.py html_theme_options
. For example:
html_theme = 'mytheme'
html_theme_options = {
'motto': 'A picture is worth a thousand words.',
'display_gitlab': True
}
Comments
comments powered by Disqus