diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_static/placeholder | 0 | ||||
| -rw-r--r-- | docs/beardomatic.rst | 86 | ||||
| -rw-r--r-- | docs/codedocs.rst | 5 | ||||
| -rw-r--r-- | docs/conf.py | 6 | ||||
| -rw-r--r-- | docs/contributinghowto.rst | 125 | ||||
| -rw-r--r-- | docs/deploymenthowto.rst | 2 | ||||
| -rw-r--r-- | docs/designdecisions.rst | 14 | ||||
| -rw-r--r-- | docs/foreward.rst | 18 | ||||
| -rw-r--r-- | docs/hackinghowto.rst | 105 | ||||
| -rw-r--r-- | docs/index.rst | 5 | ||||
| -rw-r--r-- | docs/mediagoblin.rst | 21 | ||||
| -rw-r--r-- | docs/softwarestack.rst | 127 | ||||
| -rw-r--r-- | docs/vision.rst (renamed from docs/workflow.rst) | 18 |
13 files changed, 319 insertions, 213 deletions
diff --git a/docs/_static/placeholder b/docs/_static/placeholder new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/docs/_static/placeholder diff --git a/docs/beardomatic.rst b/docs/beardomatic.rst new file mode 100644 index 00000000..14130f6a --- /dev/null +++ b/docs/beardomatic.rst @@ -0,0 +1,86 @@ +.. _beardomatic-chapter: + +=========================================== + 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 index 09f91274..00000000 --- a/docs/codedocs.rst +++ /dev/null @@ -1,5 +0,0 @@ -==================== - Code Documentation -==================== - -FIXME - stub! diff --git a/docs/conf.py b/docs/conf.py index 02c190a0..967d84d0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,16 +41,16 @@ master_doc = 'index' # General information about the project. project = u'GNU MediaGoblin' -copyright = u'2011, Chris Webber, et al' +copyright = u'2011, Free Software Foundation, Inc and contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.1a1' +version = '0.0.1' # The full version, including alpha/beta/rc tags. -release = '0.1a1' +release = '0.0.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst index a44c361f..f10dd72a 100644 --- a/docs/contributinghowto.rst +++ b/docs/contributinghowto.rst @@ -2,72 +2,114 @@ Contributing HOWTO ==================== -We're super glad you want to contribute! +Join the community! +=================== + +We're super glad you want to join our community! 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, painters, bakers, -candle-stick makers... +documentation writers, users, testers, evangelists, user-interface +designers, graphics designers, user-experience designers, system +administrators, friends, painters, bakers, candle-stick makers... -However, if you are a coder and you're looking to code, check out the -:ref:`hacking-howto`. +Here are some things you can do today: -The rest of this chapter talks about different things we need your -help with. + **Hang out with us** -**Become a user** + You should hang out with us! We like people like you! - We're building GNU MediaGoblin for us and for you but really - you're one of us and I am you and we are we and GNU MediaGoblin is - the walrus. - - Sign up for an account. Use the service. Relish in the thought - that this service comes with a heaping side of Freedom and you can - salt and pepper it to your liking. + At a bare minimum, join the `mailing list + <http://mediagoblin.org/join/>`_ and say, "Hi!" + + We also hang out on IRC in ``#mediagoblin`` on Freenode.net. + + + **File bugs** + + Filing bugs is a critical part of any project. For more + information on filing bugs, see :ref:`filing-bugs`. + + + **Write/Fix some code** + + If you are a coder and you're looking to code, check out the + :ref:`hacking-howto`. We even have tips on *becoming* a coder + and we're willing to help you! -**File bugs** + **Send encouragement** - Filing bugs is a critical part of any project. For more - information on filing bugs, see :ref:`filing-bugs`. + A nice word from you could send someone into a tizzy of + productive work. Ten nice words could complete a feature. + One hundred nice words could get us to the next milestone. + Send it to the `mailing list <http://mediagoblin.org/join/>`_ + or hop into ``#mediagoblin`` on Freenode.net and let us know. -**Translate GNU MediaGoblin** - Knowing more than one language is an important skill. If you are - multi-lingual and are interested in translating GNU MediaGoblin, - see :ref:`translating`. + **Spread the word** + The seductive call of Free Software services is a powerful + one, but many cannot hear it because it'd drowned out by the + rush hour traffic honking of proprietary walled gardens and + faux free services. Yuck! Be the sweet chirrup of the bird + amidst the din! Tell others that there is a better way to + live! -**Create a theme** + FIXME - do we want to talk about ways to spread the word? - As people deploy their own GNU MediaGoblin instances, good themes - are a must have! For more information on theming, see - :ref:`theming-howto`. + FIXME - how can people notify us that they're spreading the + word? -**Spread the word** +We're still working on project infrastructure. We hope to have the +bits in place for these additional things to do in the coming months: - The seductive call of Free Software services is a powerful one, - but many cannot hear it because it'd drowned out by the rush hour - traffic honking of proprietary walled gardens and faux free - services. Yuck! Be the sweet chirrup of the bird amidst the din! - Tell others that there is a better way to live! + **Become a user** - FIXME - do we want to talk about ways to spread the word? + We're building GNU MediaGoblin for us and for you but really + you're one of us and I am you and we are we and GNU + MediaGoblin is the walrus. + + Sign up for an account. Use the service. Relish in the + thought that this service comes with a heaping side of Freedom + and you can salt and pepper it to your liking. + + + **Help other users** - FIXME - how can people notify us that they're spreading the word? + Have you spent time with GNU MediaGoblin? If so, your + experience and wisdom are invaluable and you're the best + person we can think of to help other users with their + questions. -**Run your own instance** + **Run your own instance** - Are there things about our instance you want to change? Are there - things about other instances you wish were different? That's - great--you can run your own instance! + Are there things about our instance you want to change? Are + there things about other instances you wish were different? + Want to test upcoming changes? Want to create patches to + implement things you need? That's great---you can run your + own instance! - For more information on deploying your own instance, see - :ref:`deployment-howto`. + For more information on deploying your own instance, see + :ref:`deployment-howto`. + + + **Translate GNU MediaGoblin** + + Knowing more than one language is an important skill. If you + are multi-lingual and are interested in translating GNU + MediaGoblin, see :ref:`translating`. + + + **Create a theme** + + As people deploy their own GNU MediaGoblin instances, good + themes are a must have! For more information on theming, see + :ref:`theming-howto`. Contributing thank you drawings / copyright assignment @@ -93,8 +135,7 @@ File bugs GNU MediaGoblin uses a bug tracker called `Redmine <http://www.redmine.org>`_. -The bug tracker is at http://bugs.foocorp.net/ and bugs go in the -``GNU mediagoblin`` project. +The bug tracker is at `<http://bugs.foocorp.net/projects/mediagoblin>`_. A good bug report has the following things in it: diff --git a/docs/deploymenthowto.rst b/docs/deploymenthowto.rst index 684ac1b1..d943e276 100644 --- a/docs/deploymenthowto.rst +++ b/docs/deploymenthowto.rst @@ -9,3 +9,5 @@ Step 1: Write code that can be deployed. Step 2: ? Step 3: Write the deployment guide and profit! + +But seriously, this is a stub since we're not quite there, yet. diff --git a/docs/designdecisions.rst b/docs/designdecisions.rst index 6156d523..3398c24b 100644 --- a/docs/designdecisions.rst +++ b/docs/designdecisions.rst @@ -17,11 +17,11 @@ Chris Webber on "Why Python": 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. + Landscape`_). 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 + 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 @@ -159,14 +159,16 @@ Why Sphinx for documentation Will Kahn-Greene on "Why Sphinx": - Sphinx is a fantastic tool for organizing documentation for a + `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. + MediaGoblin is being written in Python and I've done a ton of + documentation using Sphinx, it makes sense to use Sphinx for now. + +.. _Sphinx: http://sphinx.pocoo.org/ Why AGPLv3 and CC0? diff --git a/docs/foreward.rst b/docs/foreward.rst index 0a3630a1..d2b9c417 100644 --- a/docs/foreward.rst +++ b/docs/foreward.rst @@ -16,8 +16,8 @@ This manual is a living document and is in the ``mediagoblin`` repository in the ``docs/`` directory. -Who wrote this documentation -============================ +Who wrote this documentation? +============================= In no particular order: @@ -26,16 +26,18 @@ In no particular order: * Deb * Greg * Karen +* Matt +* Asheesh -How should I bring up errors in the documentation -================================================= +I found an error in the docs---who do I tell? +============================================= -There are a few ways--please pick the one most convenient to you! +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. +1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ . +2. Tell someone on IRC ``#mediagoblin`` on Freenode. +3. Send an email to Will ``willg at bluesock dot org``. When you tell us about your issue, please let us know: diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst index 96a7e1a4..8b40e37d 100644 --- a/docs/hackinghowto.rst +++ b/docs/hackinghowto.rst @@ -8,8 +8,9 @@ So you want to hack on GNU MediaGoblin? ======================================= -First thing to do is check out the Web site where we list all the -project infrastructure including: +First thing to do is check out the `Web site +<http://mediagoblin.org>`_ where we list all the project +infrastructure including: * the mailing list * the IRC channel @@ -41,7 +42,8 @@ If you're running Debian GNU/Linux or a Debian-derived distribution such as Mint or Ubuntu, running the following should install these requirements:: - sudo apt-get install mongodb git-core python python-dev python-lxml + sudo apt-get install mongodb git-core python python-dev \ + python-lxml Running bootstrap and buildout @@ -78,11 +80,34 @@ Updating dependencies --------------------- While hacking on GNU MediaGoblin over time, you'll eventually have to -update the dependencies. To do that, run:: +update your development environment. To do that, run:: ./bin/buildout +Wiping your environment for a clean-slate +----------------------------------------- + +.. Note:: + + Unless you're doing development and working on and testing creating + a new instance, you will probably never have to do this. Will + plans to do this work and thus he documented it. + + +Delete the following directories: + +* bin/ +* develop-eggs/ +* eggs/ +* mediagoblin.egg-info/ +* parts/ +* user_dev/ + +FIXME - how to drop data from mongodb? we should probably write a +script. + + Running the server ================== @@ -99,6 +124,32 @@ Run:: ./bin/nosetests +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 + + + Quickstart for Django programmers ================================= @@ -109,3 +160,49 @@ Bite-sized bugs to start with ============================= FIXME - write this + + +Tips for people new to coding +============================= + +Python +------ + +GNU MediaGoblin is written using a programming language called `Python +<http://python.org/>`_. + +There are two different incompatible iterations of Python which I'll +refer to as Python 2 and Python 3. GNU MediaGoblin is written in +Python 2 and requires Python 2.6 or 2.7. At some point, we might +switch to Python 3, but that's a future thing. + +You can learn how to code in Python 2 from several excellent books +that are freely available on the Internet: + +* `Learn Python the Hard Way <http://learnpythonthehardway.org/>`_ +* `Dive Into Pyton <http://diveintopython.org/>`_ +* `Python for Software Design <http://www.greenteapress.com/thinkpython/>`_ +* `A Byte of Python <http://www.swaroopch.com/notes/Python>`_ + +These are all excellent texts. + +FIXME - are there good quality Python tutorial videos? + + +Libraries +--------- + +GNU MediaGoblin uses a variety of libraries in order to do what it +does. These libraries are listed in the :ref:`beardomatic-chapter` +along with links to the project Web sites and documentation for the +libraries. + +There are a variety of Python-related conferences every year that have +sessions covering many aspects of these libraries. You can find them +at `Python Miro Community <http://python.mirocommunity.org>`_ [0]_. + +.. [0] This is a shameless plug. Will Kahn-Greene runs Python Miro + Community. + +If you have questions or need help, find us on the mailing list and on +IRC. 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/mediagoblin.rst b/docs/mediagoblin.rst index 6c3a8dfa..a6194dc4 100644 --- a/docs/mediagoblin.rst +++ b/docs/mediagoblin.rst @@ -5,12 +5,13 @@ What is GNU MediaGoblin ======================= -Three years ago, a number of free software luminaries got together at -the FSF office to answer the question, "What should software freedom -look like on the participatory web?" Those thinkers included Richard -Stallman - founder of the free software movement and instigator of the -GNU project, Evan Prodromou - the driving force behind Status.net, a -highly sucessful federated micro-blogging service, and FIXME. +Three years ago (2008), a number of free software luminaries got +together at the FSF office to answer the question, "What should +software freedom look like on the participatory web?" Those thinkers +included Richard Stallman---founder of the free software movement and +instigator of the GNU project, Evan Prodromou---the driving force +behind Status.net, a highly sucessful federated micro-blogging +service, and FIXME. Since that time Identi.ca and Libre.fm have answered the freedom-loving web-user's need for micro-blogging and music sharing. @@ -46,10 +47,12 @@ How can I participate? See `Get Involved <http://mediagoblin.org/join/>`. -How is this licensed? -===================== +How is GNU MediaGoblin licensed? +================================ -FIXME - write this once we work out the details +GNU MediaGoblin software is released under an AGPLv3 license. + +See the ``COPYING`` file in the source for details. Is this an official GNU Project? What does that mean? 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 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 ------------------- |