Moves docs files around so we build from source/ directory

1 files changed, 345 insertions, 0 deletions

diff --git a/docs/source/hackinghowto.rst b/docs/source/hackinghowto.rst
new file mode 100644
index 00000000..caafba53
--- /dev/null
+++ b/docs/source/hackinghowto.rst
@@ -0,0 +1,345 @@
+.. _hacking-howto:
+
+===============
+ Hacking HOWTO
+===============
+
+.. contents:: Sections
+   :local:
+
+
+So you want to hack on GNU MediaGoblin?
+=======================================
+
+First thing to do is check out the `Web site
+<http://mediagoblin.org/join/>`_ where we list all the project
+infrastructure including:
+
+* the IRC channel
+* the mailing list
+* the issue tracker
+
+Additionally, we have information on how to get involved, who to talk
+to, what needs to be worked on, and other things besides!
+
+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>`.
+
+Fourth, you'll need to build a development environment.  We use buildout,
+but if you want to use virtualenv, there's a set of mediocre not-very-supported
+steps in the `wiki <https://gitorious.org/mediagoblin/pages/Home>`_.
+
+
+.. _get-requirements-section:
+
+Getting requirements
+====================
+
+First, you need to have the following installed before you can build
+an environment for hacking on GNU MediaGoblin:
+
+* Python 2.6 or 2.7  - http://www.python.org/
+
+  You'll need Python as well as the dev files for building modules.
+
+* python-lxml        - http://lxml.de/
+* git                - http://git-scm.com/
+* MongoDB            - http://www.mongodb.org/
+
+If you're running Debian GNU/Linux or a Debian-derived distribution
+such as Mint or Ubuntu, running the following should install these
+requirements::
+
+    sudo apt-get install mongodb git-core python python-dev \
+         python-lxml
+
+On Fedora::
+
+    yum install mongodb-server python-paste-deploy python-paste-script \
+         git-core python python-devel python-lxml
+
+.. YouCanHelp::
+
+   If you have instructions for other GNU/Linux distributions to set
+   up requirements, let us know!
+
+
+.. _hacking-with-buildout:
+
+
+How to set up and maintain an environment for hacking with buildout
+===================================================================
+
+**Requirements**
+
+No additional requirements.
+
+
+**Create a development environment**
+
+After installing the requirements, follow these steps:
+
+1. Clone the repository::
+
+       git clone git://gitorious.org/mediagoblin/mediagoblin.git
+
+2. Bootstrap and run buildout::
+
+       cd mediagoblin
+       python bootstrap.py && ./bin/buildout
+
+
+That's it!  Using this method, buildout should create a ``user_dev``
+directory, in which certain things will be stored (media, beaker
+session stuff, etc).  You can change this, but for development
+purposes this default should be fine.
+
+
+**Updating for dependency changes**
+
+While hacking on GNU MediaGoblin over time, you'll eventually have to
+update your development environment because the dependencies have
+changed.  To do that, run::
+
+    ./bin/buildout && ./bin/gmg migrate
+
+
+**Updating for 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
+
+
+Running the server
+==================
+
+If you want to get things running quickly and without hassle, just
+run::
+
+    ./lazyserver.sh
+
+This will start up a python server where you can begin playing with
+mediagoblin.  It will also run celery in "always eager" mode so you
+don't have to start a separate process for it.
+
+This is fine in development, but if you want to actually run celery
+separately for testing (or deployment purposes), you'll want to run
+the server independently::
+
+    ./bin/paster serve paste.ini --reload
+
+
+Running celeryd
+===============
+
+If you aren't using ./lazyserver.sh or otherwise aren't running celery
+in always eager mode, you'll 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::
+
+    CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
+
+
+Running the test suite
+======================
+
+Run::
+
+    ./runtests.sh
+
+
+Running a shell
+===============
+
+If you want a shell with your database pre-setup and an instantiated
+application ready and at your fingertips....
+
+Run::
+
+    ./bin/gmg shell
+
+
+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.
+
+If it's installed, check the mongodb log.  On my machine, that's 
+``/var/log/mongodb/mongodb.log``.  If you see something like::
+
+    old lock file: /var/lib/mongodb/mongod.lock.  probably means...
+
+in that case you might have had an unclean shutdown.  Try::
+
+    sudo mongod --repair
+
+If that didn't work, just delete the lock file and relaunch mongodb.
+
+Anyway, then start the mongodb server in whatever way is appropriate
+for your distro / OS.
+
+
+pkg_resources.DistributionNotFound: distribute
+----------------------------------------------
+
+If you get this while running buildout::
+
+   pkg_resources.DistributionNotFound: distribute
+
+Try this commmand instead::
+
+   python bootstrap.py --distribute && ./bin/buildout
+
+
+Wiping your user data
+=====================
+
+.. Note::
+
+   Unless you're doing development and working on and testing creating
+   a new instance, you will probably never have to do this.  Will
+   plans to do this work and thus he documented it.
+
+.. YouCanHelp::
+
+   If you're familiar with MongoDB, we'd love to get a `script that
+   removes all the GNU MediaGoblin data from an existing instance
+   <http://bugs.foocorp.net/issues/296>`_.  Let us know!
+
+
+Quickstart for Django programmers
+=================================
+
+We're not using Django, but the codebase is very Django-like in its
+structure.
+
+* ``routing.py`` is like ``urls.py`` in Django
+* ``models.py`` has mongokit ORM definitions
+* ``views.py`` is where the views go
+
+We're using MongoDB.  Basically, instead of a relational database with
+tables, you have a big JSON structure which acts a lot like a Python
+dict.
+
+
+.. YouCanHelp::
+
+   If there are other things that you think would help orient someone
+   new to GNU MediaGoblin but coming from Django, let us know!
+
+
+Bite-sized bugs to start with
+=============================
+
+**May 3rd, 2011**:  We don't have a list of bite-sized bugs, yet, but
+this is important to us.  If you're interested in things to work on,
+let us know on `the mailing list <http://mediagoblin.org/join/>`_ or
+on the `IRC channel <http://mediagoblin.org/join/>`_.
+
+
+Tips for people new to coding
+=============================
+
+Learning Python
+---------------
+
+GNU MediaGoblin is written using a programming language called `Python
+<http://python.org/>`_.
+
+There are two different incompatible iterations of Python which I'll
+refer to as Python 2 and Python 3.  GNU MediaGoblin is written in
+Python 2 and requires Python 2.6 or 2.7.  At some point, we might
+switch to Python 3, but that's a future thing.
+
+You can learn how to code in Python 2 from several excellent books
+that are freely available on the Internet:
+
+* `Learn Python the Hard Way <http://learnpythonthehardway.org/>`_
+* `Dive Into Pyton <http://diveintopython.org/>`_
+* `Python for Software Design <http://www.greenteapress.com/thinkpython/>`_
+* `A Byte of Python <http://www.swaroopch.com/notes/Python>`_
+
+These are all excellent texts.
+
+.. YouCanHelp::
+
+   If you know of other good quality Python tutorials and Python
+   tutorial videos, let us know!
+
+
+Learning Libraries GNU MediaGoblin uses
+---------------------------------------
+
+GNU MediaGoblin uses a variety of libraries in order to do what it
+does.  These libraries are listed in the :ref:`codebase-chapter`
+along with links to the project Web sites and documentation for the
+libraries.
+
+There are a variety of Python-related conferences every year that have
+sessions covering many aspects of these libraries.  You can find them
+at `Python Miro Community <http://python.mirocommunity.org>`_ [0]_.
+
+.. [0] This is a shameless plug.  Will Kahn-Greene runs Python Miro
+   Community.
+
+If you have questions or need help, find us on the mailing list and on
+IRC.
+
+
+.. _hacking-howto-git:
+
+Learning git
+------------
+
+git is an interesting and very powerful tool.  Like all powerful
+tools, it has a learning curve.
+
+If you're new to git, we highly recommend the following resources for
+getting the hang of it:
+
+* `Learn Git <http://learn.github.com/p/intro.html>`_ --- the GitHub
+  intro to git
+* `Pro Git <http://progit.org/book/>`_ --- fantastic book
+* `Git casts <http://gitcasts.com/>`_ --- screencast covering git
+  usage
+* `Git Reference <http://gitref.org/>`_ --- Git reference that makes
+  it easier to get the hang of git if you're coming from other version
+  control systems
+
+There's also a git mission at `OpenHatch <http://openhatch.org/>`_.
+
+
+Learning other utilities
+------------------------
+
+The `OpenHatch <http://openhatch.org/>`_ site has a series of
+`training missions <http://openhatch.org/missions/>`_ which are
+designed to help you learn how to use these tools.
+
+If you're new to tar, diff, patch and git, we highly recommend you sign
+up with OpenHatch and do the missions.