Configuration¶
The Press theme webpage is composed of a fixed header, a sidebar and main content area.
On Sphinx project’s conf.py: set the theme name to press.
html_theme = "press"
See details on Sphinx theming docs.
Config values¶
Basic configuration on conf.py:
html_logo¶
If defined shows an image instead of project name on page top-left (link to index page).
html_logo = '_static/myproject-logo.png'
html_css_files¶
Adds custom CSS files to the theme
# Here we assume that the file is at _static/css/custom.css
html_css_files = ["css/custom.css"]
html_external_links¶
If provided, creates external links (e.g. Github) in the top right corner:
html_theme_options = {
"external_links": [
("Github", "https://github.com/username/repo"),
("Other", "https://bla.com")
]
}
Templates¶
The util folder contains Jinja2 snippets to be included,
from main templates. Those can be easily replaced by theme users.
To change site/page structure you should extend pages and give new implementations for Jinja2 blocks.
Jinja2 templates and blocks are organized as follow:
layout.html¶
Blocks on HTML head:
htmltitle- HTML page titlecss- include theme’s CSS filesscripts- include theme’s javascript filesextrahead- empty by default, to be used by theme users
Blocks on HTML body:
container - whole visible page
header- fixed header (includesutil/navbar.html)navbar.html- apart from home-link includesutil/navlinks.html&util/extlinks.html
sidebarside_links- includesutil/navlinks.html&util/extlinks.htmlinclude all templates listed on
html_sidebarsconfig
documentbody_header- includesutil/bodyheader.htmlbody- main content generated from ReST documentsfooter- includesutil/pagenav.html&util/footer.html
util/extlinks.html¶
External links defined by theme’s user.
util/searchbox.html¶
Form to perform site search.
util/sidetoc.html¶
Navigation from toctree.
util/bodyheader.html¶
Breadcrumbs and page navigation.