User guide

For installation instructions, see Installation.

If you get stuck, you can look for information in Sphinx’s documentation for using a theme, but in theory all the relevant information is collected right here. Open a Github issue if something’s missing.

This document assumes you’ve already set up Sphinx and have some docs written.

sphinx-better-theme is meant to be customized primarily via CSS. There are a few options that you can set in conf.py, but they are either functionality-related or appear in more than one annoying-to-type selector.

CSS-based customization is currently limited by the inflexibility of the markup. That situation should improve over time as sphinx-better-theme sheds more and more of its inheritance from the basic theme.

Feel free to read the conf.py for this site to get ideas for your own site. In particular, consider setting html_short_title to "Home" so the first breadcrumb says “Home” instead of your long project title.

Theme options

Unless you’re creating your own theme that inherits from sphinx-better-theme, you’re probably setting theme options in conf.py. Here are all the defaults:

html_theme_options = {
  # show sidebar on the right instead of on the left
  'rightsidebar': False,

  # inline CSS to insert into the page if you're too lazy to make a
  # separate file
  'inlinecss': '',

  # CSS files to include after all other CSS files
  # (refer to by relative path from conf.py directory)
  'cssfiles': [],

  # show a big text header with the value of html_title
  'showheader': True,

  # show the breadcrumbs and index|next|previous links at the top of
  # the page
  'showrelbartop': True,
  # same for bottom of the page
  'showrelbarbottom': True,

  # show search in the sidebar. some of us think Sphinx's search is
  # garbage and just want it to go away.
  'enablesidebarsearch': True,

  # show the self-serving link in the footer
  'linktotheme': True,

  # width of the sidebar. page width is determined by a CSS rule.
  # I prefer to define things in rem because it scales with the
  # global font size rather than pixels or the local font size.
  'sidebarwidth': '15rem',

  # color of all body text
  'textcolor': '#000000',

  # color of all headings (<h1> tags); defaults to the value of
  # textcolor, which is why it's defined here at all.
  'headtextcolor': '',

  # color of text in the footer, including links; defaults to the
  # value of textcolor
  'footertextcolor': '',

  # Google Analytics info
  'ga_ua': '',
  'ga_domain': '',
}

Adding static files

(This is all vanilla Sphinx, but you’ll need it for the next section.)

  1. Configure a static directory:

    html_static_path = ['_static']
    
  2. Put a file in it (e.g. docs/_static/cat.png).

  3. Use it.

Using CSS files

  1. Add your CSS file as a static file as above.
  2. Add the file name (relative to the static directory) to the html_theme_options['cssfiles'] list.

You should read better’s CSS files to get an idea of what selectors you should override. better_basic.css_t is my fork of the basic theme’s CSS, and better.css_t is the stylistic overrides.

Using Javascript files

  1. Add your Javascript file as a static file as above.
  2. Add the file name (relative to the static directory) to the html_theme_options['scriptfiles'] list.