From 97a1c2766de81e8da3f39d96eb6b896cb61deb5d Mon Sep 17 00:00:00 2001 From: Dave Snider Date: Sun, 3 Nov 2013 14:50:38 -0800 Subject: [PATCH] update readme for contributors --- README.rst | 73 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 63 insertions(+), 10 deletions(-) diff --git a/README.rst b/README.rst index af3005a5..e3cca1a8 100644 --- a/README.rst +++ b/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_, -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! +The sphinx_rtd_theme is primarily a sass_ project that requires a few other sass libraries. I'm +using bower_ to manage these dependencies and compass_ to build the css. The good news is +I have a very nice set of grunt_ operations that will not only load these dependecies, but watch +for changes, rebuild the sphinx demo docs and build a distributable version of the theme in the ``dist`` +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. -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. +Set up your environment +----------------------- -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 ====