sphinx-better-theme: usable documentation

sphinx-better-theme is a theme for Sphinx that looks nice, is easy to style with CSS, works well on small screens and mobile devices, and organizes the page better. See Why? for details.

You can get the source and open issues on Github.

• Installation
  • Read the Docs Configuration
• User guide
  • Theme options
  • Adding static files
  • Using CSS files
  • Using Javascript files
  • Suggested Sphinx options
• Demos
  • Sphinx style demo
  • reStructuredText style demo
• Why?
  • It looks nice
  • It’s easy to style with CSS
  • The navigation is laid out better
  • It works well on small screens and mobile devices
  • Deficiencies

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.

Projects using sphinx-better-theme

• mrjob has tens of thousands of words of guides and API docs.
• Pillow is the modern fork of the Python Imaging Library and recently got a new set of docs.
• zhang-shasha is a single page of simple Python library documentation.
• pivotal_tools is a single page of command line tool documentation.
• Rsyslog is a rocket-fast system for log processing. It offers high-performance, great security features and a modular design.

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.1.4: Semantic versioning, mobile bug fixes, sidebar slimming, style improvements

v0.1.5: Remove a few useless options, allow remote CSS files, fix Google Analytics integration

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

kr-sphinx-themes has two nice, clean themes used for many popular (and good-looking) projects.

sphinx-readable-theme is a theme optimized for readability of apidoc-generated docs.

sphinxtheme-readability is another attempt at a clean theme.

Cloud is a feature-rich theme with a responsive layout.

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

Read the Docs uses a 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.

The Julia language also uses an interesting custom theme.