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

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 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/navlinks.html

Links taken from TOCs defined on master document.

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.

util/pagenav.html

Links for previous/next page.

util/footer.html

Copyright information.