StarMirror/sol2
1
0
Fork 0
mirror of https://github.com/ThePhD/sol2.git synced 2024-03-22 13:10:44 +08:00
Code Issues Projects Releases Wiki Activity

update the readme

Browse Source
This commit is contained in:
Dave Snider 2013-10-29 22:45:38 -07:00
parent df08b518e4
commit 24a05b9306
1 changed files with 30 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
README.rst
View File

@ -2,6 +2,8 @@
.. _bower: http://www.bower.io
.. _sphinx: http://www.sphinx-doc.org
.. _compass: http://www.compass-style.org
.. _wyrm: http://www.github.com/snide/wyrm/
.. _grunt: http://www.gruntjs.com
**************************
Read the Docs Sphinx Theme
@ -20,7 +22,7 @@ if you're just tyring to use it on your project outside of that site.
Installation
============
Symlink the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
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
conf.py file:
@ -29,14 +31,32 @@ conf.py file:
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]
How the Table of Contents builds
================================
Currently the left menu will build based upon any `toctree(s)` defined in your index.rst file.
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.
Contributing or modifying the theme
===================================
To work on this theme you'll need to install bower_. 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, making sure to use compass_ to compile down to css.
If you'd like to see your changes made to master, send me a pull request.
This theme relies pretty heavily on a couple other sass libraries, but most notably wyrm_,
a frotend 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.
To load the depencies you'll need to install bower_, which itself requires node to run.
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.
I've also set up a basic grunt_ command to update any dependencies and compile the css.
TODO
====
* Separate some sass variables at the theme level so you can overwrite some basic colors.
* Get large tables working better in responsive environments.
* Add the ability to set a logo.