2013-10-18 04:29:09 +08:00
|
|
|
.. _readthedocs.org: http://www.readthedocs.org
|
|
|
|
|
.. _bower: http://www.bower.io
|
|
|
|
|
.. _sphinx: http://www.sphinx-doc.org
|
|
|
|
|
.. _compass: http://www.compass-style.org
|
2013-10-30 13:45:38 +08:00
|
|
|
.. _wyrm: http://www.github.com/snide/wyrm/
|
|
|
|
|
.. _grunt: http://www.gruntjs.com
|
2013-10-30 13:52:04 +08:00
|
|
|
.. _node: http://www.nodejs.com
|
2013-10-31 03:32:50 +08:00
|
|
|
.. _demo: http://docs.readthedocs.org
|
2013-10-18 04:29:09 +08:00
|
|
|
|
|
|
|
|
**************************
|
|
|
|
|
Read the Docs Sphinx Theme
|
|
|
|
|
**************************
|
|
|
|
|
|
2013-10-31 03:32:50 +08:00
|
|
|
View a working demo_ over on readthedocs.org_.
|
|
|
|
|
|
2013-10-30 13:45:38 +08:00
|
|
|
This is a prototype mobile-friendly sphinx_ theme I made for readthedocs.org_. It's
|
|
|
|
|
currently in development and includes some rtd variable checks that can be ignored
|
2013-10-30 13:52:04 +08:00
|
|
|
if you're just trying to use it on your project outside of that site.
|
2013-10-18 04:29:09 +08:00
|
|
|
|
2013-10-18 22:59:08 +08:00
|
|
|
.. image:: screen_mobile.png
|
|
|
|
|
:width: 100%
|
|
|
|
|
|
2013-10-18 04:29:09 +08:00
|
|
|
Installation
|
|
|
|
|
============
|
|
|
|
|
|
2013-10-30 13:45:38 +08:00
|
|
|
Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
|
|
|
|
|
``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
|
2013-10-18 04:29:09 +08:00
|
|
|
conf.py file:
|
|
|
|
|
|
2013-10-30 13:45:38 +08:00
|
|
|
.. code-block::
|
2013-10-18 04:29:09 +08:00
|
|
|
|
|
|
|
|
html_theme = "sphinx_rtd_theme"
|
|
|
|
|
html_theme_path = ["_themes", ]
|
|
|
|
|
|
2013-10-30 13:45:38 +08:00
|
|
|
How the Table of Contents builds
|
|
|
|
|
================================
|
|
|
|
|
|
2013-10-30 13:52:04 +08:00
|
|
|
Currently the left menu will build based upon any ``toctree(s)`` defined in your index.rst file.
|
2013-10-30 13:45:38 +08:00
|
|
|
It outputs 2 levels of depth, which should give your visitors a high level of access to your
|
|
|
|
|
docs. If no toctrees are set the theme reverts to sphinx's usual local toctree.
|
|
|
|
|
|
|
|
|
|
It's important to note that if you don't follow the same styling for your rST headers across
|
|
|
|
|
your documents, the toctree will misbuild, and the resulting menu might not show the correct
|
|
|
|
|
depth when it renders.
|
|
|
|
|
|
2013-10-18 04:29:09 +08:00
|
|
|
Contributing or modifying the theme
|
|
|
|
|
===================================
|
|
|
|
|
|
2013-10-30 13:45:38 +08:00
|
|
|
This theme relies pretty heavily on a couple other sass libraries, but most notably wyrm_,
|
2013-10-30 13:52:04 +08:00
|
|
|
a frontend library I'm currently building. I've tried to keep most of the layout specific
|
|
|
|
|
code in this repo, but a lot of the rST text formatting is done over there. Wyrm is pretty
|
|
|
|
|
spartan and undocumented at the moment, so if you simply want to create some bug issues
|
|
|
|
|
for me rather than setting up a pull request, that's totally OK with me!
|
2013-10-18 04:29:09 +08:00
|
|
|
|
2013-10-30 13:52:04 +08:00
|
|
|
To load the dependencies you'll need to install bower_, which itself requires node_ to run.
|
2013-10-30 13:45:38 +08:00
|
|
|
Then simply run a ``bower install`` in the root directory to install the dependencies.
|
|
|
|
|
Once installed, make your sass changes to the ``sphix_rtd_theme/sass`` directory.
|
2013-10-18 04:29:09 +08:00
|
|
|
|
2013-10-30 13:45:38 +08:00
|
|
|
I've also set up a basic grunt_ command to update any dependencies and compile the css.
|
2013-10-19 06:15:23 +08:00
|
|
|
|
2013-10-30 13:45:38 +08:00
|
|
|
TODO
|
|
|
|
|
====
|
|
|
|
|
* Separate some sass variables at the theme level so you can overwrite some basic colors.
|
|
|
|
|
* Add the ability to set a logo.
|
