Heavy documentation updates

* Nixed codedocs and software stack chapters in favor of a chapter on
  Beardomatic!
* Switched workflow to vision and added an additional caveat at the top

diff --git a/docs/beardomatic.rst b/docs/beardomatic.rst
new file mode 100644 (file)
index 0000000..5ebeb23
--- /dev/null
+++ b/docs/beardomatic.rst
@@ -0,0 +1,84 @@
+===========================================
+ Beardomatic: Infrastructure Documentation
+===========================================
+
+What the hell is Beardomatic?
+=============================
+
+You might be wondering, "Gah!  What the hell is Beardomatic!?"
+
+Well, I'll tell you.  GNU MediaGoblin is a piece of software that sits
+on a stack of libraries that do a bunch of stuff.  It makes it easier
+to differentiate the bits of code that encompass GNU MediaGoblin from
+the bits of code that GNU MediaGoblin sit on top of.  Thus, we came up
+with the TOTALLY AWESOME name Beardomatic.
+
+Now you might be saying, "Holy crap!?  Another web framework?  Are you
+going to write a mocking framework and an enumeration library, too!?"
+
+No, we're not.  We're just calling this Beardomatic so that it's
+easier to talk about things.  However, at some point, we can take
+these infrastructure bits from GNU MediaGoblin and turn them into a
+full-blown "web framework".  We wouldn't do this to compete for
+mindshare with other web frameworks.  We would do this to make it
+easier for us to bootstrap other similar projects.
+
+
+Beardomatic software stack
+==========================
+
+Beardomatic is a software stack "web framework" composed of the
+following bits:
+
+* Project infrastructure
+
+  * `Python <http://python.org/>`_: the language we're using to write
+    this
+
+  * `Nose <http://somethingaboutorange.com/mrl/projects/nose/>`_:
+    for unit tests
+
+  * `buildout <http://www.buildout.org/>`_: for getting dependencies,
+    building a runtime environment, ...
+
+* Data storage
+
+  * `MongoDB <http://www.mongodb.org/>`_: the document database backend
+    for storage
+
+* Web application
+
+  * `Paste Deploy <http://pythonpaste.org/deploy/>`_ and 
+    `Paste Script <http://pythonpaste.org/script/>`_: we'll use this for
+    configuring and launching the application
+
+  * `WebOb <http://pythonpaste.org/webob/>`_: nice abstraction layer
+    from HTTP requests, responses and WSGI bits
+
+  * `Routes <http://routes.groovie.org/>`_: for URL routing
+
+  * `Beaker <http://beaker.groovie.org/>`_: for handling sessions
+
+  * `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
+
+  * `MongoKit <http://namlook.github.com/mongokit/>`_: the lightweight
+    ORM for MongoDB we're using which will make it easier to define
+    structures and all that
+
+  * `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
+    validation, and abstraction from HTML forms
+
+  * `Celery <http://celeryproject.org/>`_: for task queuing (resizing
+    images, encoding video, ...)
+
+  * `RabbitMQ <http://www.rabbitmq.com/>`_: for sending tasks to celery
+
+* Front end
+
+  * `JQuery <http://jquery.com/>`_: for groovy JavaScript things
+
+
+How to ... in Beardomatic?
+==========================
+
+FIXME - write this

diff --git a/docs/codedocs.rst b/docs/codedocs.rst
deleted file mode 100644 (file)
index 09f9127..0000000
--- a/docs/codedocs.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-====================
- Code Documentation
-====================
-
-FIXME - stub!

diff --git a/docs/index.rst b/docs/index.rst
index fb92d139db9bbb42bbb7b95dff846585519924a5..fc8cc64246adcc983698163d816665af548eb711 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -17,10 +17,9 @@ Table of Contents:
    deploymenthowto
    hackinghowto
    theminghowto
-   softwarestack
    designdecisions
-   workflow
-   codedocs
+   vision
+   beardomatic
 
 
 Indices and tables

diff --git a/docs/softwarestack.rst b/docs/softwarestack.rst
deleted file mode 100644 (file)
index 024f0d5..0000000
--- a/docs/softwarestack.rst
+++ /dev/null
@@ -1,127 +0,0 @@
-=======
- Stack
-=======
-
-The software stack for this project might change over time, but this
-is what we're thinking right now.
-
-There's some explanation of design decisions in the
-:ref:`design-decisions-chapter`.
-
-
-Python
-======
-
-* http://python.org/
-
-The core team does a lot of work in Python and it's the language we're
-most likely to do a project like this in.
-
-
-MongoDB
-=======
-
-* http://www.mongodb.org/
-
-A "document database".  Because it's extremely flexible and scales up
-well, but I guess not down well.
-
-
-MongoKit
-========
-
-* http://namlook.github.com/mongokit/
-
-A lightweight ORM for mongodb.  Helps us define our structures better,
-does schema validation, schema evolution, and helps make things more
-fun and pythonic.
-
-
-Jinja2
-======
-
-* http://jinja.pocoo.org/docs/
-
-For templating.  Pretty much django templates++ but allows us to pass
-arguments into method calls instead of writing custom tags.
-
-
-WTForms
-=======
-
-* http://wtforms.simplecodes.com/
-
-For form handling, validation, abstraction.  Almost just like Django's
-templates.
-
-
-WebOb
-=====
-
-* http://pythonpaste.org/webob/
-
-Gives nice request/response objects (also somewhat Django-ish).
-
-
-Paste Deploy and Paste Script
-=============================
-
-* http://pythonpaste.org/deploy/
-* http://pythonpaste.org/script/
-
-This will be the default way of configuring and launching the
-application.  Since GNU MediaGoblin will be fairly WSGI minimalist though,
-you can probably use other ways to launch it, though this will be the
-default.
-
-
-Routes
-======
-
-* http://routes.groovie.org/
-
-For URL Routing.  It works well enough.
-
-
-JQuery
-======
-
-* http://jquery.com/
-
-For all sorts of things on the JavaScript end of things, for all sorts
-of reasons.
-
-
-Beaker
-======
-
-* http://beaker.groovie.org/
-
-For sessions, because that seems like it's generally considered the
-way to go I guess.
-
-
-Nose
-====
-
-* http://somethingaboutorange.com/mrl/projects/nose/1.0.0/
-
-For unit tests because it makes testing a bit nicer.
-
-
-Celery
-======
-
-* http://celeryproject.org/
-
-For task queueing (resizing images, encoding video, ...).
-
-
-RabbitMQ
-========
-
-* http://www.rabbitmq.com/
-
-For sending tasks to celery, because I guess that's what most people
-do.  Might be optional, might also let people use MongoDB for this if
-they want.

diff --git a/docs/workflow.rst b/docs/vision.rst
similarity index 92%
rename from docs/workflow.rst
rename to docs/vision.rst
index b72031deca274a76f6a35325bc23852be7671b2e..fad248dfa7239ca661c113a30ad5da4b09cd2a7d 100644 (file)
--- a/docs/workflow.rst
+++ b/docs/vision.rst
@@ -1,21 +1,26 @@
-==========================================================================
- Design Document: Workflow, and other structurally significant braindumps
-==========================================================================
+=========================================
+ Design Document: GNU MediaGoblin vision
+=========================================
 
 .. Note::
 
    When we get a wiki, this will get moved there.  It's here for now
    mostly because we didn't have a better place for it.
 
+.. Note::
+
+   By the time you read this, it's very likely it'll be out of date.
 
-This document attempts to describe the envisioned workflow of
-mediagoblin, from a structural standpoint.  For now, *nothing* in this
+
+This document attempts to describe the envisioned workflow of GNU
+MediaGoblin, from a structural standpoint.  For now, *nothing* in this
 document is probably the eventual, final way that things will work.
 Eventually as things come to exist, this document will hopefully be
 refactored to describe how things *do* work.
 
 This documented on hopes, dreams, rainbows, and unicorns.  And it will
-come to fulfillment through a lot of hard work.
+come to fulfillment through a lot of hard work.  Your hard work and my
+hard work.
 
 
 Look and feel
@@ -31,6 +36,7 @@ here.
 
 http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/
 
+
 User profile mockup
 -------------------