Lots of documentation changes

* added a YouCanHelp directive to replace FIXMEs and encourage contributors
  to help out
* moved some bits around between the hacking howto and the codebase documents
* expanded on the stub nature of the theming howto
* tweaked some other text

8 files changed, 156 insertions, 36 deletions

diff --git a/docs/codebase.rst b/docs/codebase.rst
index 2c73e7d3..1f6ce220 100644
--- a/docs/codebase.rst
+++ b/docs/codebase.rst
@@ -7,6 +7,18 @@
 This chapter covers the libraries that GNU MediaGoblin uses as well as
 various recipes for getting things done.
 
+.. Note::
+
+   This chapter is in flux.  Clearly there are things here that aren't
+   documented.  If there's something you have questions about, please
+   ask!
+
+   See `the join page on the website <http://mediagoblin.org/join/>`_
+   for where we hang out.
+
+For more information on how to get started hacking on GNU MediaGoblin,
+see :ref:`hacking-howto`.
+
 
 Software Stack
 ==============
@@ -59,6 +71,55 @@ Software Stack
   * `JQuery <http://jquery.com/>`_: for groovy JavaScript things
 
 
+
+What's where
+============
+
+After you've run buildout, you're faced with the following directory
+tree::
+
+    mediagoblin/
+    |- mediagoblin/              source code
+    |  |- tests/
+    |  |- templates/
+    |  |- auth/
+    |  \- submit/
+    |- docs/                     documentation
+    |
+    |        the rest of these directories are generated by
+    |        buildout.
+    |
+    |- bin/                      scripts
+    |- develop-eggs/
+    |- eggs/
+    |- mediagoblin.egg-info/
+    |- parts/
+    |- user_dev/                 sessions, etc
+
+
+As you can see, all the code for GNU MediaGoblin is in the
+``mediagoblin`` directory.
+
+Here are some interesting files and what they do:
+
+:routing.py: maps url paths to views
+:views.py:   views handle http requests
+:models.py:  holds the mongodb schemas---these are the data structures 
+             we're working with
+
+You'll notice that there are several sub-directories: tests,
+templates, auth, submit, ...
+
+``tests`` holds the unit test code.
+
+``templates`` holds all the templates for the output.
+
+``auth`` and ``submit`` are modules that enacpsulate authentication
+and media item submission.  If you look in these directories, you'll
+see they have their own ``routing.py``, ``view.py``, and
+``models.py`` in addition to some other code.
+
+
 Recipes
 =======
 
diff --git a/docs/conf.py b/docs/conf.py
index 967d84d0..fedaf33c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -16,7 +16,7 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -25,7 +25,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ["mgext.youcanhelp"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst
index a452f2d0..56a80b91 100644
--- a/docs/contributinghowto.rst
+++ b/docs/contributinghowto.rst
@@ -4,11 +4,16 @@
  Contributing HOWTO
 ====================
 
+.. _join-the-community-section:
+
 Join the community!
 ===================
 
 We're super glad you want to join our community!
 
+See `the join page on the website <http://mediagoblin.org/join/>`_ for
+where we hang out.
+
 There are a variety of ways you can help us and become part of the
 team.  We're not just looking for coders!  We're also looking for
 documentation writers, users, testers, evangelists, user-interface
diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst
index 26267b7f..fe2411bb 100644
--- a/docs/hackinghowto.rst
+++ b/docs/hackinghowto.rst
@@ -9,16 +9,20 @@ So you want to hack on GNU MediaGoblin?
 =======================================
 
 First thing to do is check out the `Web site
-<http://mediagoblin.org>`_ where we list all the project
+<http://mediagoblin.org/join/>`_ where we list all the project
 infrastructure including:
 
-* the mailing list
 * the IRC channel
-* the bug tracker
+* 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.
+
 
 How to set up and maintain an environment for hacking
 =====================================================
@@ -80,10 +84,16 @@ Updating dependencies
 ---------------------
 
 While hacking on GNU MediaGoblin over time, you'll eventually have to
-update your development environment.  To do that, run::
+update your development environment because the dependencies have
+changed.  To do that, run::
 
     ./bin/buildout
 
+.. Note::
+
+    You only need to do this when dependencies are updated.  You don't
+    need to do this when you've made code changes.
+
 
 Wiping your environment for a clean-slate
 -----------------------------------------
@@ -104,8 +114,12 @@ Delete the following directories:
 * parts/
 * user_dev/
 
-FIXME - how to drop data from mongodb?  we should probably write a
-script.
+
+.. YouCanHelp::
+
+   If you're familiar with MongoDB and bash, we'd love to get a bash
+   script that removes all the GNU MediaGoblin data from an existing
+   MongoDB instance.  Let us know!
 
 
 Running the server
@@ -124,42 +138,34 @@ Run::
     ./bin/nosetests
 
 
-What's where
-============
+Quickstart for Django programmers
+=================================
 
-After you've run buildout, you're faced with the following directory
-tree::
+We're not using Django, but the codebase is very Django-like in its
+structure.
 
-    mediagoblin/
-    |- mediagoblin/              source code
-    |  |- tests/
-    |  |- templates/
-    |  |- auth/
-    |  \- submit/
-    |- docs/                     documentation
-    |
-    |        the rest of these directories are generated by
-    |        buildout.
-    |
-    |- bin/                      scripts
-    |- develop-eggs/
-    |- eggs/
-    |- mediagoblin.egg-info/
-    |- parts/
-    |- user_dev/                 sessions, etc
+* ``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.
 
 
-Quickstart for Django programmers
-=================================
+.. YouCanHelp::
 
-FIXME - write this
+   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
 =============================
 
-FIXME - write this
+**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
@@ -186,7 +192,10 @@ that are freely available on the Internet:
 
 These are all excellent texts.
 
-FIXME - are there good quality Python tutorial videos?
+.. YouCanHelp::
+
+   If you know of other good quality Python tutorials and Python
+   tutorial videos, let us know!
 
 
 Learning Libraries GNU MediaGoblin uses
diff --git a/docs/mediagoblin.rst b/docs/mediagoblin.rst
index a6194dc4..6d511850 100644
--- a/docs/mediagoblin.rst
+++ b/docs/mediagoblin.rst
@@ -44,7 +44,7 @@ dedicated to computer user freedom.
 How can I participate?
 ======================
 
-See `Get Involved <http://mediagoblin.org/join/>`.
+See `Get Involved <http://mediagoblin.org/join/>`_ on the website..
 
 
 How is GNU MediaGoblin licensed?
diff --git a/docs/mgext/__init__.py b/docs/mgext/__init__.py
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/docs/mgext/__init__.py
diff --git a/docs/mgext/youcanhelp.py b/docs/mgext/youcanhelp.py
new file mode 100644
index 00000000..a99d0e4d
--- /dev/null
+++ b/docs/mgext/youcanhelp.py
@@ -0,0 +1,44 @@
+from docutils import nodes
+
+from sphinx.util.compat import Directive, make_admonition
+
+class youcanhelp_node(nodes.Admonition, nodes.Element):
+    pass
+
+class YouCanHelp(Directive):
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self):
+        ad = make_admonition(
+            youcanhelp_node,
+            self.name,
+            ["You Can Help!"],
+            self.options,
+            self.content,
+            self.lineno,
+            self.content_offset,
+            self.block_text,
+            self.state,
+            self.state_machine)
+        ad[0].line = self.lineno
+        return ad
+
+def visit_youcanhelp_node(self, node):
+    self.visit_admonition(node)
+
+def depart_youcanhelp_node(self, node):
+    self.depart_admonition(node)
+
+def setup(app):
+    app.add_node(
+        youcanhelp_node,
+        html=(visit_youcanhelp_node, depart_youcanhelp_node),
+        latex=(visit_youcanhelp_node, depart_youcanhelp_node),
+        text=(visit_youcanhelp_node, depart_youcanhelp_node)
+        )
+    
+    app.add_directive('youcanhelp', YouCanHelp)
diff --git a/docs/theminghowto.rst b/docs/theminghowto.rst
index 23f9cb1b..7b40685f 100644
--- a/docs/theminghowto.rst
+++ b/docs/theminghowto.rst
@@ -4,4 +4,5 @@
  Theming HOWTO
 ===============
 
-FIXME - stub!
+We haven't implemented the necessary scaffolding to allow for theming
+yet.  Thus, this chapter is a stub.