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 :doc:`why` for details.

You can get the source and open issues `on Github.`_

.. _Sphinx: http://sphinx-doc.org
.. _on Github.: https://github.com/irskep/sphinx-better-theme

.. toctree::
    :maxdepth: 2

    installation.rst
    guide.rst
    demos.rst
    why.rst

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 <http://mrjob.readthedocs.org/en/latest/>`_ has tens of thousands of
  words of guides and API docs.

* `Pillow <http://pillow.readthedocs.org/en/latest/>`_ is the modern fork of
  the Python Imaging Library and recently got a new set of docs.

* `zhang-shasha <http://zhang-shasha.readthedocs.org/en/latest/>`_ is a single
  page of simple Python library documentation.

* `pivotal_tools <http://pythonhosted.org/pivotal_tools/>`_ is a single page of
  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.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 <https://github.com/kennethreitz/kr-sphinx-themes>`_ has two
nice, clean themes used for many popular (and good-looking) projects.

`sphinx-readable-theme
<https://sphinx-readable-theme.readthedocs.org/en/latest/>`_ is a theme
optimized for readability of *apidoc*-generated docs.

`sphinxtheme-readability
<https://sphinxtheme-readability.readthedocs.org/en/latest/>`_ is another
attempt at a clean theme.

`Cloud <http://pythonhosted.org/cloud_sptheme/cloud_theme.html>`_ is a 
feature-rich theme with a responsive layout.

A few different themes are available for download at
`sphinx-themes. <http://vkvn.github.io/sphinx-themes/>`_

`Read the Docs <https://readthedocs.org/>`_ uses a custom theme as the default
for all docs hosted there.

The `Guzzle <http://guzzlephp.org/>`_ project uses a `heavily customized
theme`_ that's also used by `aws-cli <http://aws.amazon.com/cli/>`_.

.. _heavily customized theme: https://github.com/guzzle/guzzle_sphinx_theme

The `Julia language <https://github.com/JuliaLang/juliadoc>`_ also uses an
interesting custom theme.

.. possible projects to convince to switch:
.. (Steve's to-do list for "write other projects' docs for them")

.. pymongo (http://api.mongodb.org/python/current/)

.. pyzmq (http://zeromq.github.io/pyzmq/)

.. rsa (http://stuvel.eu/files/python-rsa-doc/index.html)

.. scss (http://pythonhosted.org/scss/)

.. boto (http://docs.pythonboto.org/en/latest/)

.. pip (http://pip.readthedocs.org/en/latest/)

.. runsnakerun (https://launchpad.net/runsnakerun)

.. ply (https://github.com/dabeaz/ply)

.. smiley (https://smiley.readthedocs.org/en/latest/)

.. sphinxcontrib-epydoc (http://sphinxcontrib-epydoc.readthedocs.org/en/0.6/)
.. sphinxcontrib-issuetracker (http://sphinxcontrib-issuetracker.readthedocs.org/en/0.11/)
.. sphinxcontrib-napoleon (https://sphinxcontrib-napoleon.readthedocs.org/en/latest/)
.. sphinxcontrib-programoutput (https://sphinxcontrib-programoutput.readthedocs.org/en/latest/)
.. sphinx-me (https://sphinx-me.readthedocs.org/en/latest/)
.. sphinxcontrib-sqltable (http://sphinxcontrib-sqltable.readthedocs.org/en/latest/)
.. sphinxcontrib-spelling (http://sphinxcontrib-spelling.readthedocs.org/en/latest/)
.. sphinxcontrib-fulltoc (http://sphinxcontrib-fulltoc.readthedocs.org/en/latest/)
