From 34366952a21f040ee5ca3df899a82f9e6bd9cffe Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 24 Apr 2011 19:46:48 -0400 Subject: [PATCH] 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 --- docs/beardomatic.rst | 84 ++++++++++++++++++++ docs/codedocs.rst | 5 -- docs/index.rst | 5 +- docs/softwarestack.rst | 127 ------------------------------ docs/{workflow.rst => vision.rst} | 18 +++-- 5 files changed, 98 insertions(+), 141 deletions(-) create mode 100644 docs/beardomatic.rst delete mode 100644 docs/codedocs.rst delete mode 100644 docs/softwarestack.rst rename docs/{workflow.rst => vision.rst} (92%) diff --git a/docs/beardomatic.rst b/docs/beardomatic.rst new file mode 100644 index 00000000..5ebeb239 --- /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 `_: the language we're using to write + this + + * `Nose `_: + for unit tests + + * `buildout `_: for getting dependencies, + building a runtime environment, ... + +* Data storage + + * `MongoDB `_: the document database backend + for storage + +* Web application + + * `Paste Deploy `_ and + `Paste Script `_: we'll use this for + configuring and launching the application + + * `WebOb `_: nice abstraction layer + from HTTP requests, responses and WSGI bits + + * `Routes `_: for URL routing + + * `Beaker `_: for handling sessions + + * `Jinja2 `_: the templating engine + + * `MongoKit `_: the lightweight + ORM for MongoDB we're using which will make it easier to define + structures and all that + + * `WTForms `_: for handling, + validation, and abstraction from HTML forms + + * `Celery `_: for task queuing (resizing + images, encoding video, ...) + + * `RabbitMQ `_: for sending tasks to celery + +* Front end + + * `JQuery `_: 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 index 09f91274..00000000 --- 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 fb92d139..fc8cc642 100644 --- 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 index 024f0d5d..00000000 --- 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 b72031de..fad248df 100644 --- 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 ------------------- -- 2.25.1