Overhauls hacking howto

* reworks virtualenv section to be way better
* reworks buildout section to mirror virtualenv section
* reworks other sections that depend on which development environment
  building method you chose

docs/hackinghowto.rst

@@ -23,13 +23,21 @@ Second thing to do is take a look at :ref:`codebase-chapter` where
 we've started documenting how GNU MediaGoblin is built and how to add
 new things.
 
+Third you'll need to :ref:`get the requirements
+<get-requirements-section>`.
 
-How to set up and maintain an environment for hacking
+Fourth, you'll need to build a development environment.  For this step, there are two options: 
-=====================================================
 
+1. :ref:`virtualenv <hacking-with-virtualenv>` OR
+2. :ref:`buildout and bootstrap <hacking-with-buildout>`
+
+Pick one---don't do both!
+
+
+.. _get-requirements-section:
 
 Getting requirements
---------------------
+====================
 
 First, you need to have the following installed before you can build
 an environment for hacking on GNU MediaGoblin:
@@ -49,13 +57,94 @@ requirements::
     sudo apt-get install mongodb git-core python python-dev \
          python-lxml
 
-After getting the requirements, there are two ways to build a development environment:
+.. YouCanHelp::
 
-1. Running bootstrap and buildout, OR
+   If you have instructions for other GNU/Linux distributions to set
-2. Creating a virtual environment
+   up requirements, let us know!
 
-Pick one---don't do both!
 
+.. _hacking-with-virtualenv:
+
+How to set up and maintain an environment for hacking with virtualenv
+=====================================================================
+
+.. Note::
+
+   Either follow the instructions in this section OR follow the ones
+   in :ref:`hacking-with-buildout`.  But don't do both!
+
+
+**Requirements**
+
+* virtualenv: http://pypi.python.org/pypi/virtualenv
+* virtualenv wrapper: http://www.doughellmann.com/projects/virtualenvwrapper/
+* git: http://git-scm.com/
+
+
+**Create a development environment**
+
+1. Clone the repository::
+
+       git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
+
+2. Create a virtual environment::
+
+       mkvirtualenv --no-site-packages mediagoblin
+
+3. If that doesn't put you in the virutal environment you just
+   created, then do::
+
+       workon mediagoblin
+
+4. Run::
+
+       python setup.py develop
+
+That's it!
+
+
+**Activating a virtual environment**
+
+When you want to work on GNU MediaGoblin, you need to activate the
+virtual environment like this::
+
+    workon mediagoblin
+
+
+**Deactivating a virtual environment**
+
+If you want to deactivate it, you can do this::
+
+    deactivate
+
+
+**Updating a virtual environment with dependency changes**
+
+1. Enter the virtual environment.
+
+2. Run::
+
+      python setup.py develop
+
+
+**Updating a virtual environment with code changes**
+
+You don't need to do anything---code changes are automatically
+available.
+
+
+**Deleting a virtual environment**
+
+At some point you may want to delete your virtual environment.
+Perhaps it's to start over.  Perhaps it's so you can test building
+development environments with virtualenv.
+
+To do this, do::
+
+    rmvirtualenv mediagoblin
+
+
+.. _hacking-with-buildout:
 
 Creating a dev environment with bootstrap and buildout
 ------------------------------------------------------
@@ -63,9 +152,16 @@ Creating a dev environment with bootstrap and buildout
 .. Note::
 
    Either follow the instructions in this section OR follow the ones
-   in the next one---don't do both!
+   in :ref:`hacking-with-virtualenv`.  But don't do both!
 
 
+**Requirements**
+
+No additional requirements.
+
+
+**Create a development environment**
+
 After installing the requirements, follow these steps:
 
 1. Clone the repository::
@@ -84,13 +180,7 @@ session stuff, etc).  You can change this, but for development
 purposes this default should be fine.
 
 
-.. Note::
+**Updating for dependency changes**
-
-   We used `zc.buildout <http://www.buildout.org/>`_ because it
-   involves fewer steps to get things running and less knowledge of
-   Python packaging.  However, if you prefer to use `virtualenv
-   <http://pypi.python.org/pypi/virtualenv>`_, that should work just
-   fine.
 
 While hacking on GNU MediaGoblin over time, you'll eventually have to
 update your development environment because the dependencies have
@@ -98,76 +188,38 @@ changed.  To do that, run::
 
     ./bin/buildout
 
-.. Note::
 
-    You only need to do this when dependencies are updated.  You don't
+**Updating for code changes**
-    need to do this when you've made code changes.
 
+You don't need to do anything---code changes are automatically
+available.
+
+
+**Deleting your buildout**
+
+At some point, you may want to delete your buildout.  Perhaps it's to
+start over.  Perhaps it's to test building development environments
+with buildout.
+
+To do this, do::
+
+    rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev
+
+
+.. _env_with_virtualenv:
 
 Creating a dev environment with virtualenv
 ------------------------------------------
 
-.. Note::
-
-   Either follow the instructions in this section OR follow the ones
-   in the previous one---don't do both!
-
-The following assumes you have these things installed:
-
-1. virtualenv:
-
-   http://pypi.python.org/pypi/virtualenv
-
-2. virtualenv wrapper:
-
-   http://www.doughellmann.com/projects/virtualenvwrapper/
-
-3. git:
-
-   http://git-scm.com/
-
-
-Follow these steps:
-
-1. Clone the repository::
-
-       git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
-
-2. Create a virtual environment::
-
-       mkvirtualenv --no-site-packages mediagoblin
-
-3. If that doesn't put you in the virutal environment you just created, then do::
-
-       workon mediagoblin
-
-4. Run::
-
-       python setup.py develop
-
-
-That's it!
-
-When you want to work on GNU MediaGoblin, you need to activate the
-virtual environment like this::
-
-    workon mediagoblin
-
-If you want to deactivate it, you can do this::
-
-    deactivate
-
-.. Note::
-
-   You don't have to do anything additional to move changes you're
-   making to your virtual environment because the virtual environment
-   is pointing at the actual code files.
-
 
 Running the server
 ==================
 
-Run::
+If you did virtualenv, run::
+
+    paster serve mediagoblin.ini --reload
+
+If you did buildout, run::
 
     ./bin/paster serve mediagoblin.ini --reload
 
@@ -179,7 +231,11 @@ You need to do this if you want your media to process and actually
 show up.  It's probably a good idea in development to have the web
 server (above) running in one terminal and celeryd in another window.
 
-Run::
+If you did virtualenv, run::
+
+    CELERY_CONFIG_MODULE=mediagoblin.celery_setup.from_celery celeryd
+
+If you did buildout, run::
 
     CELERY_CONFIG_MODULE=mediagoblin.celery_setup.from_celery ./bin/celeryd
 
@@ -187,13 +243,30 @@ Run::
 Running the test suite
 ======================
 
-Run::
+If you did virtualenv, run::
+
+    nosetests
+
+If you did buildout, run::
 
     ./bin/nosetests
 
 
-Wiping your environment for a clean-slate
+Troubleshooting
------------------------------------------
+===============
+
+pymongo.errors.AutoReconnect: could not find master/primary
+-----------------------------------------------------------
+
+If you see this::
+
+    pymongo.errors.AutoReconnect: could not find master/primary
+
+then make sure mongodb is installed and running.
+
+
+Wiping your user data
+=====================
 
 .. Note::
 
@@ -201,17 +274,6 @@ Wiping your environment for a clean-slate
    a new instance, you will probably never have to do this.  Will
    plans to do this work and thus he documented it.
 
-
-Delete the following directories:
-
-* bin/
-* develop-eggs/
-* eggs/
-* mediagoblin.egg-info/
-* parts/
-* user_dev/
-
-
 .. YouCanHelp::
 
    If you're familiar with MongoDB, we'd love to get a `script that