diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/designdecisions.rst | 170 | ||||
| -rw-r--r-- | docs/foreward.rst | 31 | ||||
| -rw-r--r-- | docs/index.rst | 13 | ||||
| -rw-r--r-- | docs/installation.rst | 5 | ||||
| -rw-r--r-- | docs/softwarestack.rst | 127 |
5 files changed, 346 insertions, 0 deletions
diff --git a/docs/designdecisions.rst b/docs/designdecisions.rst new file mode 100644 index 00000000..f30c1ca5 --- /dev/null +++ b/docs/designdecisions.rst @@ -0,0 +1,170 @@ +.. _design-decisions-chapter: + +================== + Design Decisions +================== + +This chapter talks a bit about design decisions. + + +Why Python +========== + +Chris Webber on "Why Python": + + Because I know Python, love Python, am capable of actually making + this thing happen in Python (I've worked on a lot of large free + software web applications before in Python, including `Miro + Community`_, the `Miro Guide`_, a large portion of `Creative + Commons`_, and a whole bunch of things while working at `Imaginary + Landscape`_). I know Python, I can make this happen in Python, me + starting a project like this makes sense if it's done in Python. + + You might say that PHP is way more deployable, that Rails has way + more cool developers riding around on fixie bikes, and all of + those things are true. But I know Python, like Python, and think + that Python is pretty great. I do think that deployment in Python + is not as good as with PHP, but I think the days of shared hosting + are (thankfully) coming to an end, and will probably be replaced + by cheap virtual machines spun up on the fly for people who want + that sort of stuff, and Python will be a huge part of that future, + maybe even more than PHP will. The deployment tools are getting + better. Maybe we can use something like Silver Lining. Maybe we + can just distribute as ``.debs`` or ``.rpms``. We'll figure it + out when we get there. + + Regardless, if I'm starting this project, which I am, it's gonna + be in Python. + +.. _Miro Community: http://mirocommunity.org/ +.. _Miro Guide: http://miroguide.org/ +.. _Creative Commons: http://creativecommons.org/ +.. _Imaginary Landscape: http://www.imagescape.com/ + + +Why WSGI Minimalism +=================== + +Chris Webber on "Why WSGI Minimalism": + + If you notice in the technology list above, I list a lot of + components that are very `Django Project`_, but not actually + Django components. What can I say, I really like a lot of the + ideas in Django! Which leads to the question: why not just use + Django? + + While I really like Django's ideas and a lot of its components, I + also feel that most of the best ideas in Django I want have been + implemented as good or even better outside of Django. I could + just use Django and replace the templating system with Jinja2, and + the form system with wtforms, and the database with MongoDB and + MongoKit, but at that point, how much of Django is really left? + + I also am sometimes saddened and irritated by how coupled all of + Django's components are. Loosely coupled yes, but still coupled. + WSGI has done a good job of providing a base layer for running + applications on and if you know how to do it yourself [1]_, it's + not hard or many lines of code at all to bind them together + without any framework at all (not even say `Pylons`_, `Pyramid`_ + or `Flask`_ which I think are still great projects, especially for + people who want this sort of thing but have no idea how to get + started). And even at this already really early stage of writing + MediaGoblin, that glue work is mostly done. + + Not to say I don't think Django isn't great for a lot of things. + For a lot of stuff, it's still the best, but not for MediaGoblin, + I think. + + One thing that Django does super well though is documentation. It + still has some faults, but even with those considered I can hardly + think of any other project in Python that has as nice of + documentation as Django. It may be worth learning some lessons on + documentation from Django [2]_, on that note. + + I'd really like to have a good, thorough hacking-howto and + deployment-howto, especially in the former making some notes on + how to make it easier for Django hackers to get started. + +.. _Django Project: http://www.djangoproject.com/ +.. _Pylons: http://pylonshq.com/ +.. _Pyramid: http://docs.pylonsproject.org/projects/pyramid/dev/ +.. _Flask: http://flask.pocoo.org/ + +.. [1] http://pythonpaste.org/webob/do-it-yourself.html +.. [2] http://pycon.blip.tv/file/4881071/ + + +Why MongoDB +=========== + +Chris Webber on "Why MongoDB": + + In case you were wondering, I am not a NOSQL fanboy, I do not go + around telling people that MongoDB is web scale. Actually my + choice for MongoDB isn't scalability, though scaling up really + nicely is a pretty good feature and sets us up well in case large + volume sites eventually do use MediaGoblin. But there's another + side of scalability, and that's scaling down, which is important + for federation, maybe even more important than scaling up in an + ideal universe where everyone ran servers out of their own + housing. As a memory-mapped database, MongoDB is pretty hungry, + so actually I spent a lot of time debating whether the inability + to scale down as nicely as something like SQL has with sqlite + meant that it was out. + + But I decided in the end that I really want MongoDB, not for + scalability, but for flexibility. Schema evolution pains in SQL + are almost enough reason for me to want MongoDB, but not quite. + The real reason is because I want the ability to eventually handle + multiple media types through MediaGoblin, and also allow for + plugins, without the rigidity of tables making that difficult. In + other words, something like:: + + {"title": "Me talking until you are bored", + "description": "blah blah blah", + "media_type": "audio", + "media_data": { + "length": "2:30", + "codec": "OGG Vorbis"}, + "plugin_data": { + "licensing": { + "license": "http://creativecommons.org/licenses/by-sa/3.0/"}}} + + + Being able to just dump media-specific information in a media_data + hashtable is pretty great, and even better is having a plugin + system where you can just let plugins have their own entire + key-value space cleanly inside the document that doesn't interfere + with anyone else's stuff. If we were to let plugins to deposit + their own information inside the database, either we'd let plugins + create their own tables which makes SQL migrations even harder + than they already are, or we'd probably end up creating a table + with a column for key, a column for value, and a column for type + in one huge table called "plugin_data" or something similar. (Yo + dawg, I heard you liked plugins, so I put a database in your + database so you can query while you query.) Gross. + + I also don't want things to be too lose so that we forget or lose + the structure of things, and that's one reason why I want to use + MongoKit, because we can cleanly define a much structure as we + want and verify that documents match that structure generally + without adding too much bloat or overhead (mongokit is a pretty + lightweight wrapper and doesn't inject extra mongokit-specific + stuff into the database, which is nice and nicer than many other + ORMs in that way). + + +Why Sphinx for documentation +============================ + +Will Kahn-Greene on "Why Sphinx": + + Sphinx is a fantastic tool for organizing documentation for a + Python-based project that makes it pretty easy to write docs that + are readable in source form and can be "compiled" into HTML, LaTeX + and other formats. + + There are other doc systems out there, but given that GNU + MediaGoblin is being written in Python, it makes sense to use + Sphinx for now. + diff --git a/docs/foreward.rst b/docs/foreward.rst new file mode 100644 index 00000000..4fc8152a --- /dev/null +++ b/docs/foreward.rst @@ -0,0 +1,31 @@ +========== + Foreward +========== + +What is GNU MediaGoblin +======================= + +See the web-site at http://mediagoblin.org/ . + + +Who wrote this documentation +============================ + +* Chris Webber +* Will Kahn-Greene + + +How should I bring up errors in the documentation +================================================= + +There are a few ways--please pick the one most convenient to you! + +1. Send an email to Will ``willg at bluesock dot org``. +2. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ . +3. Tell someone on IRC ``#mediagoblin`` on Freenode. + +When you tell us about your issue, please let us know: + +* where you are looking (in git? url of the web-page?) +* what the issue is +* your thoughts on how to resolve it diff --git a/docs/index.rst b/docs/index.rst index 94f6c7f7..6f96ff8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,11 +6,24 @@ Welcome to GNU MediaGoblin's documentation! =========================================== +This documentation covers the GNU MediaGoblin software. It is versioned +alongside the code and the source for this documentation is located in +the mediagoblin repository in the ``docs/`` directory. + +It is also viewable on the Web site in HTML form. + + Contents: .. toctree:: :maxdepth: 2 + foreward + softwarestack + installation + designdecisions + + Indices and tables ================== diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..2dfd467d --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,5 @@ +============== + Installation +============== + +FIXME - this page is a stub! diff --git a/docs/softwarestack.rst b/docs/softwarestack.rst new file mode 100644 index 00000000..024f0d5d --- /dev/null +++ b/docs/softwarestack.rst @@ -0,0 +1,127 @@ +======= + 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. |