sphinx-better-theme

sphinx-better-theme is a theme for Sphinx that tries to be better than the built-in themes. See Anticipatory FAQ for details.

You can get the source and open issues on Github.

• User guide
  • Theme options
  • Adding static files
  • Using CSS files
  • Using Javascript files
• Demos
  • Sphinx style demo
  • reStructuredText style demo
• Anticipatory FAQ
  • Better how?
  • Why encourage customization?
  • How does this theme encourage customization better than the default?
  • Why not just contribute to Sphinx itself?

Compatibility

sphinx-better-theme is compatible with Sphinx 0.6.4+ and Jinja 2.3.1+. Older versions may work but have not been tested.

Installation

Get it from PyPI:

> pip install sphinx-better-theme

Or download the zip file and run the usual command:

> python setup.py install

Once the package is installed, make these changes to conf.py to direct Sphinx to use the theme:

from better import better_theme_path
html_theme_path = [better_theme_path]
html_theme = 'better'

Read the Docs Configuration

Using sphinx-better-theme with Read the Docs is easy. You just need to tell it to install the package.

First, create a requirements.txt file just for your docs. It must contain at least the line sphinx-better-theme==0.13, as well as any other dependencies your docs might have that are separate from your project’s dependencies. I suggest putting it in your docs folder, e.g. at docs/requirements.txt.

Then, go to your Read the Docs admin panel. Make sure the Use virtualenv checkbox is enabled, and set the Requirements file field to the path to your requirements.txt file.

Read the Docs should now build and display your theme correctly, assuming your conf.py contains the changes described above in Installation.

Projects using sphinx-better-theme

• mrjob (both narrative and API docs)
• pivotal_tools (single-page command line tool documentation)

History/Roadmap

v0.1: Basic CSS-customizable style that looks nice in its default state

v0.11: Add easy Google Analytics support

v0.12: Improve base styles, responsive layout, document usage with Read the Docs

v0.13: Further style improvements, relbar shows only full titles of next/previous links

v0.2: (planned) Rewrite markup to be semantic and customizable

v1.0: (planned) Extreme documentation polish and rounding out of edge cases

Other themes to check out

Cloud is a nice, feature-rich theme from which I plan to steal more than one feature.

A few different themes are available for download at sphinx-themes.

Read the Docs uses a nice custom theme as the default for all docs hosted there.

The Guzzle project uses a heavily customized theme that’s also used by aws-cli.