update readme for contributors

README.rst

@@ -2,6 +2,7 @@
 .. _bower: http://www.bower.io
 .. _sphinx: http://www.sphinx-doc.org
 .. _compass: http://www.compass-style.org
+.. _sass: http://www.sass-lang.com
 .. _wyrm: http://www.github.com/snide/wyrm/
 .. _grunt: http://www.gruntjs.com
 .. _node: http://www.nodejs.com
@@ -23,7 +24,7 @@ if you're just trying to use it on your project outside of that site.
 Installation
 ============
 
-Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
+Symlink or subtree the ``dist/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:
 
@@ -46,17 +47,69 @@ depth when it renders.
 Contributing or modifying the theme
 ===================================
 
-This theme relies pretty heavily on a couple other sass libraries, but most notably wyrm_,
+The sphinx_rtd_theme is primarily a sass_ project that requires a few other sass libraries. I'm
-a frontend library I'm currently building. I've tried to keep most of the layout specific
+using bower_ to manage these dependencies and compass_ to build the css. The good news is
-code in this repo, but a lot of the rST text formatting is done over there. Wyrm is pretty
+I have a very nice set of grunt_ operations that will not only load these dependecies, but watch
-spartan and undocumented at the moment, so if you simply want to create some bug issues
+for changes, rebuild the sphinx demo docs and build a distributable version of the theme in the ``dist``
-for me rather than setting up a pull request, that's totally OK with me!
+directory. The bad news is this means you'll need to set up your environment similar to that
+of a front-end developer (vs. that of a python developer). That means installing node and ruby.
 
-To load the dependencies you'll need to install bower_, which itself requires node_ to run.
+Set up your environment
-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.
+1. Install sphinx_ into a virtual environment.
+
+..code-block::
+  pip install sphinx
+
+2. Install node, bower and grunt.
+
+..code-block
+
+    // Install node
+    brew install node
+
+    // Install node package manager
+    curl https://npmjs.org/install.sh | sh
+
+    // Install bower and grunt
+    npm install -g bower grunt-cli
+
+Now that our environment is set up, make sure you're in your virtual environment, go to
+this repository in your terminal and run grunt:
+
+..code-block
+
+    grunt
+
+This default task will do the following **very cool things that make it worth the trouble**.
+
+1. It'll install and update any bower dependencies.
+2. It'll run sphinx and build new docs.
+3. It'll watch for changes to the sass files and build css from the changes.
+4. It'll rebuild the sphinx docs anytime it notices a change to .rst, .html, .js
+   or .css files.
+
+When you're done with your edits, you can run ``grunt dist`` to clean out the old
+files and rebuild a new distribution, compressing the css and cleaning out
+extraneous files.
+
+Dude, come on, just for a theme file?
+-------------------------------------
+
+Frontend development is quickly evolving to a package managed system with sane build tools
+that are separate from the backend.
+
+Working with a staticly generated system like sphinx is a pain in the ass for a designer because you
+need to do so much rebuilding. Tools like grunt_ and sass_ really, really help make my life easier.
+While I know you might be used to the simplicity of other sphinx themes that are just built
+in CSS, the majority of the sphinx_rtd_theme comes from other libraries and I want to avoid
+copy / pasting code in here just to build it.
+
+OK fine, what files should I be editing then?
+---------------------------------------------
+
+Edit files in the ``src`` directory only. Primarily you'll want to edit the .html and .sass files.
 
 TODO
 ====