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_sidebars

By default the sidebars include only: searchbox and a global TOC tree. See docs on html_sidebars.

html_sidebars = {'**': ['util/searchbox.html', 'util/sidetoc.html']}

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"]

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 title

  • css - include theme’s CSS files

  • scripts - include theme’s javascript files

  • extrahead - empty by default, to be used by theme users

Blocks on HTML body:

container - whole visible page

  • header - fixed header (includes util/navbar.html)

    • navbar.html - apart from home-link includes util/navlinks.html & util/extlinks.html

  • sidebar

    • side_links - includes util/navlinks.html & util/extlinks.html

    • include all templates listed on html_sidebars config

  • document

    • body_header - includes util/bodyheader.html

    • body - main content generated from ReST documents

    • footer - includes util/pagenav.html & util/footer.html

util/navbar.html

Header content. Left side contains home-link with name.

Right side contains links from util/navlinks.html and util/extlinks.html.

util/searchbox.html

Form to perform site search.

util/sidetoc.html

Navigation from toctree.

util/bodyheader.html

Breadcrumbs and page navigation.

util/pagenav.html

Links for previous/next page.