From 34366952a21f040ee5ca3df899a82f9e6bd9cffe Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 24 Apr 2011 19:46:48 -0400 Subject: 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/vision.rst | 142 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/workflow.rst | 136 ---------------------------------------------- 6 files changed, 228 insertions(+), 271 deletions(-) create mode 100644 docs/beardomatic.rst delete mode 100644 docs/codedocs.rst delete mode 100644 docs/softwarestack.rst create mode 100644 docs/vision.rst delete mode 100644 docs/workflow.rst 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/vision.rst b/docs/vision.rst new file mode 100644 index 00000000..fad248df --- /dev/null +++ b/docs/vision.rst @@ -0,0 +1,142 @@ +========================================= + 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 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. Your hard work and my +hard work. + + +Look and feel +============= + +Default look and feel +--------------------- + +Mairin Duffy made mockups for something called Design Hub. That +project did a number of things differently than the way we intend to +go, but it's probably a good idea to steal a good number of ideas from +here. + +http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/ + + +User profile mockup +------------------- + +Here's an ascii art mockup on how things might look for a user's page:: + + _____ + |_( )_| USER NAME + | | | + |_/_\_| + + Recent artwork: + ___________________ ___________________________ + | ___ ___ ___ | |_About_User_Name___________| + | |pic| |pic| |pic| | | | + | |___| |___| |___| | | Some sort of self- | + | ___ ___ ___ | | description probably goes | + < | |pic| |pic| |pic| | > | here | + | |___| |___| |___| | | | + | ___ ___ ___ | | | + | |pic| |pic| |pic| | | | + | |___| |___| |___| | | | + |___________________| |___________________________| + + ___________________________ + Recent favorites: |_Recent_activity___________| + ___________________ | New picture: DragonFace | + | ___ ___ ___ | | 4/2/2010 | + | |pic| |pic| |pic| | |---------------------------| + | |___| |___| |___| | | Sup yall this is some kind| + | ___ ___ ___ | | of mini blogpost. Maybe | + < | |pic| |pic| |pic| | > | the interface will allow | + | |___| |___| |___| | | for this? | + | ___ ___ ___ | |___________________________| + | |pic| |pic| |pic| | + | |___| |___| |___| | ___________________________ + |___________________| |_External_comments_here____| + | Dang! This stuff rocks | + | - Joe 4/2/2010 | + |---------------------------| + | Nice job on the dragon | + | - Morgan 4/2/2010 | + '---------------------------' + +So there's this type of interface that puts a lot of different types +of info on the same screen. I'm not sure that I like it. It's +possible we'll go with something much more minimalist. Maybe we'll go +with something "tabbed" the way statusnet / http://identi.ca is on +user pages. + +It's possible that we could support multiple profile styles here, +and you could load whatever profile style you want as set by user +preferences? + + +Uploading mockup +---------------- + +Here's an uploading mockup:: + + Upload an image + + [ Title ] + + Upload: [ ] [Browse] + ___________________________________________ + | | + | | + | o0O | + | o ' | + | o_.' | + | | + | Uploading... OK | <-, + | Resizing... OK | | + | | Area replaced w/ resized + | | image when done + |___________________________________________| + ________________ + License |_CC BY-SA_____|V| + ___________________________________________ + | Description goes here. | + | You can type it up in here and everything | + | and it'll show up under the image. | + | | + | Possibly we should allow some kind of | + | markup... maybe markdown? | + '___________________________________________' + + __________________________________________ + |> Advanced | + ------------------------------------------ + + +Customizability +--------------- + +General site theming customizability is pretty easy! Since we're +using `Jinja `_ we can just set up +user-overriding directories. + +We'll also figure out some sort of way to provide theming "packages", +eventually. + + diff --git a/docs/workflow.rst b/docs/workflow.rst deleted file mode 100644 index b72031de..00000000 --- a/docs/workflow.rst +++ /dev/null @@ -1,136 +0,0 @@ -========================================================================== - Design Document: Workflow, and other structurally significant braindumps -========================================================================== - -.. 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. - - -This document attempts to describe the envisioned workflow of -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. - - -Look and feel -============= - -Default look and feel ---------------------- - -Mairin Duffy made mockups for something called Design Hub. That -project did a number of things differently than the way we intend to -go, but it's probably a good idea to steal a good number of ideas from -here. - -http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/ - -User profile mockup -------------------- - -Here's an ascii art mockup on how things might look for a user's page:: - - _____ - |_( )_| USER NAME - | | | - |_/_\_| - - Recent artwork: - ___________________ ___________________________ - | ___ ___ ___ | |_About_User_Name___________| - | |pic| |pic| |pic| | | | - | |___| |___| |___| | | Some sort of self- | - | ___ ___ ___ | | description probably goes | - < | |pic| |pic| |pic| | > | here | - | |___| |___| |___| | | | - | ___ ___ ___ | | | - | |pic| |pic| |pic| | | | - | |___| |___| |___| | | | - |___________________| |___________________________| - - ___________________________ - Recent favorites: |_Recent_activity___________| - ___________________ | New picture: DragonFace | - | ___ ___ ___ | | 4/2/2010 | - | |pic| |pic| |pic| | |---------------------------| - | |___| |___| |___| | | Sup yall this is some kind| - | ___ ___ ___ | | of mini blogpost. Maybe | - < | |pic| |pic| |pic| | > | the interface will allow | - | |___| |___| |___| | | for this? | - | ___ ___ ___ | |___________________________| - | |pic| |pic| |pic| | - | |___| |___| |___| | ___________________________ - |___________________| |_External_comments_here____| - | Dang! This stuff rocks | - | - Joe 4/2/2010 | - |---------------------------| - | Nice job on the dragon | - | - Morgan 4/2/2010 | - '---------------------------' - -So there's this type of interface that puts a lot of different types -of info on the same screen. I'm not sure that I like it. It's -possible we'll go with something much more minimalist. Maybe we'll go -with something "tabbed" the way statusnet / http://identi.ca is on -user pages. - -It's possible that we could support multiple profile styles here, -and you could load whatever profile style you want as set by user -preferences? - - -Uploading mockup ----------------- - -Here's an uploading mockup:: - - Upload an image - - [ Title ] - - Upload: [ ] [Browse] - ___________________________________________ - | | - | | - | o0O | - | o ' | - | o_.' | - | | - | Uploading... OK | <-, - | Resizing... OK | | - | | Area replaced w/ resized - | | image when done - |___________________________________________| - ________________ - License |_CC BY-SA_____|V| - ___________________________________________ - | Description goes here. | - | You can type it up in here and everything | - | and it'll show up under the image. | - | | - | Possibly we should allow some kind of | - | markup... maybe markdown? | - '___________________________________________' - - __________________________________________ - |> Advanced | - ------------------------------------------ - - -Customizability ---------------- - -General site theming customizability is pretty easy! Since we're -using `Jinja `_ we can just set up -user-overriding directories. - -We'll also figure out some sort of way to provide theming "packages", -eventually. - - -- cgit v1.2.3