diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 29 | ||||
| -rw-r--r-- | docs/designdecisions.rst | 329 | ||||
| -rw-r--r-- | docs/hackinghowto.rst | 345 | ||||
| -rw-r--r-- | docs/source/_static/placeholder (renamed from docs/_static/placeholder) | 0 | ||||
| -rw-r--r-- | docs/source/_templates/mg_theme/layout.html | 39 | ||||
| -rw-r--r-- | docs/source/_templates/mg_theme/static/default.css_t | 299 | ||||
| -rw-r--r-- | docs/source/_templates/mg_theme/theme.conf | 31 | ||||
| -rw-r--r-- | docs/source/codebase.rst (renamed from docs/codebase.rst) | 2 | ||||
| -rw-r--r-- | docs/source/conf.py (renamed from docs/conf.py) | 29 | ||||
| -rw-r--r-- | docs/source/contributinghowto.rst (renamed from docs/contributinghowto.rst) | 6 | ||||
| -rw-r--r-- | docs/source/deploymenthowto.rst (renamed from docs/deploymenthowto.rst) | 4 | ||||
| -rw-r--r-- | docs/source/foreword.rst (renamed from docs/foreword.rst) | 0 | ||||
| -rw-r--r-- | docs/source/git.rst (renamed from docs/git.rst) | 2 | ||||
| -rw-r--r-- | docs/source/goblin.png (renamed from docs/goblin.png) | bin | 47763 -> 47763 bytes | |||
| -rw-r--r-- | docs/source/index.rst (renamed from docs/index.rst) | 2 | ||||
| -rw-r--r-- | docs/source/mediagoblin.rst (renamed from docs/mediagoblin.rst) | 6 | ||||
| -rw-r--r-- | docs/source/mgext/__init__.py (renamed from docs/mgext/__init__.py) | 0 | ||||
| -rw-r--r-- | docs/source/mgext/youcanhelp.py (renamed from docs/mgext/youcanhelp.py) | 0 | ||||
| -rw-r--r-- | docs/source/snugglygoblin.png (renamed from docs/snugglygoblin.png) | bin | 163754 -> 163754 bytes | |||
| -rw-r--r-- | docs/source/theminghowto.rst (renamed from docs/theminghowto.rst) | 0 | ||||
| -rw-r--r-- | docs/source/vision.rst (renamed from docs/vision.rst) | 0 |
21 files changed, 431 insertions, 692 deletions
diff --git a/docs/Makefile b/docs/Makefile index 81fc3d13..0b97bf7c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,14 +5,16 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = -BUILDDIR = _build +BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make <target>' where <target> is one of" @@ -32,6 +34,9 @@ help: @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" clean: -rm -rf $(BUILDDIR)/* @@ -113,6 +118,24 @@ man: @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo diff --git a/docs/designdecisions.rst b/docs/designdecisions.rst deleted file mode 100644 index afa1e26b..00000000 --- a/docs/designdecisions.rst +++ /dev/null @@ -1,329 +0,0 @@ -.. _design-decisions-chapter: - -================== - Design Decisions -================== - -.. contents:: Sections - :local: - - -This chapter talks a bit about design decisions. - - -Why GNU MediaGoblin? -==================== - -Chris and Will on "Why GNU MediaGoblin": - - Chris came up with the name MediaGoblin. The name is pretty fun. - It merges the idea that this is a Media hosting project with - Goblin which sort of sounds like gobbling. Here's a piece of - software that gobbles up your media for all to see. - - `According to Wikipedia <http://en.wikipedia.org/wiki/Goblin>`_, a - goblin is: - - a legendary evil or mischievous illiterate creature, described - as grotesquely evil or evil-like phantom - - So are we evil? No. Are we mischievous or illiterate? Not - really. So what kind of goblin are we thinking about? We're - thinking about these goblins: - - .. figure:: goblin.png - :alt: Cute goblin with a beret. - - *Figure 1: Cute goblin with a beret. llustrated by Chris - Webber* - - .. figure:: snugglygoblin.png - :scale: 50% - :alt: Snuggly goblin with a beret. - - *Figure 2: Snuggly goblin. Illustrated by Karen Rustad* - - Those are pretty cute goblins. Those are the kinds of goblins - we're thinking about. - - Chris started doing work on the project after thinking about it - for a year. Then, after talking with Matt and Rob, it became an - official GNU project. Thus we now call it GNU MediaGoblin. - - That's a lot of letters, though, so in the interest of brevity and - facilitating easier casual conversation and balancing that with - what's important to us, we have the following rules: - - 1. "GNU MediaGoblin" is the name we're going to use in all official - capacities: web site, documentation, press releases, ... - - 2. In casual conversation, it's ok to use more casual names. - - 3. If you're writing about the project, we ask that you call it GNU - MediaGoblin. - - 4. If you don't like the name, we kindly ask you to take a deep - breath, think a happy thought about cute little goblins playing - on a playground and taking cute pictures of themselves, and let - it go. (Will added this one.) - - -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`_). 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 I list a lot of components - that are very "django-like", 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: 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 loose 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 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? -=================== - -Chris, Brett, Will, Rob, Matt, et al curated into a story where -everyone is the hero by Will on "Why AGPLv3 and CC0": - - The `AGPL v3`_ preserves the freedoms guaranteed by the GPL v3 in - the context of software as a service. Using this license ensures - that users of the service have the ability to examine the source, - deploy their own instance, and implement their own version. This - is really important to us and a core mission component of this - project. Thus we decided that the software parts should be under - this license. - - However, the project is made up of more than just software: - there's CSS, images, and other output-related things. We wanted - the templates/images/css side of the project all permissive and - permissive in the same absolutely permissive way. We're waiving - our copyrights to non-software things under the CC0 waiver. - - That brings us to the templates where there's some code and some - output. The template engine we're using is called Jinja2. It - mixes HTML markup with Python code to render the output of the - software. We decided the templates are part of the output of the - software and not the software itself. We wanted the output of the - software to be licensed in a hassle-free way so that when someone - deploys their own GNU MediaGoblin instance with their own - templates, they don't have to deal with the copyleft aspects of - the AGPLv3 and we'd be fine with that because the changes they're - making are identity-related. So at first we decided to waive our - copyrights to the templates with a CC0 waiver and then add an - exception to the AGPLv3 for the software such that the templates - can make calls into the software and yet be a separately licensed - work. However, Brett brought up the question of whether this - allows some unscrupulous person to make changes to the software - through the templates in such a way that they're not bound by the - AGPLv3: i.e. a loophole. We thought about this loophole and - between this and the extra legalese involved in the exception to - the AGPLv3, we decided that it's just way simpler if the templates - were also licensed under the AGPLv3. - - Then we have the licensing for the documentation. Given that the - documentation is tied to the software content-wise, we don't feel - like we have to worry about ensuring freedom of the documentation - or worry about attribution concerns. Thus we're waiving our - copyrights to the documentation under CC0 as well. - - Lastly, we have branding. This covers logos and other things that - are distinctive to GNU MediaGoblin that we feel represents this - project. Since we don't currently have any branding, this is an - open issue, but we're thinking we'll go with a CC BY-SA license. - - By licensing in this way, we make sure that users of the software - receive the freedoms that the AGPLv3 ensures regardless of what - fate befalls this project. - - So to summarize: - - * software (Python, JavaScript, HTML templates): licensed - under AGPLv3 - * non-software things (CSS, images, video): copyrights waived - under CC0 because this is output of the software - * documentation: copyrights waived under CC0 because it's not part - of the software - * branding assets: we're kicking this can down the road, but - probably CC BY-SA - - This is all codified in the ``COPYING`` file. - -.. _AGPL v3: http://www.gnu.org/licenses/agpl.html -.. _CC0 v1: http://creativecommons.org/publicdomain/zero/1.0/ - - -Why (non-mandatory) copyright assignment? -========================================= - -Chris Webber on "Why copyright assignment?": - - GNU MediaGoblin is a GNU project with non-mandatory but heavily - encouraged copyright assignment to the FSF. Most, if not all, of - the core contributors to GNU MediaGoblin will have done a - copyright assignment, but unlike some other GNU projects, it isn't - required here. We think this is the best choice for GNU - MediaGoblin: it ensures that the Free Software Foundation may - protect the software by enforcing the AGPL if the FSF sees fit, - but it also means that we can immediately merge in changes from a - new contributor. It also means that some significant non-FSF - contributors might also be able to enforce the AGPL if seen fit. - - Again, assignment is not mandatory, but it is heavily encouraged, - even incentivized: significant contributors who do a copyright - assignment to the FSF are eligible to have a unique goblin drawing - produced for them by the project's main founder, Christopher Allan - Webber. See :ref:`contributing-howto-chapter` for details. - - diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst deleted file mode 100644 index caafba53..00000000 --- a/docs/hackinghowto.rst +++ /dev/null @@ -1,345 +0,0 @@ -.. _hacking-howto: - -=============== - Hacking HOWTO -=============== - -.. contents:: Sections - :local: - - -So you want to hack on GNU MediaGoblin? -======================================= - -First thing to do is check out the `Web site -<http://mediagoblin.org/join/>`_ where we list all the project -infrastructure including: - -* the IRC channel -* the mailing list -* the issue tracker - -Additionally, we have information on how to get involved, who to talk -to, what needs to be worked on, and other things besides! - -Second thing to do is take a look at :ref:`codebase-chapter` where -we've started documenting how GNU MediaGoblin is built and how to add -new things. - -Third you'll need to :ref:`get the requirements -<get-requirements-section>`. - -Fourth, you'll need to build a development environment. We use buildout, -but if you want to use virtualenv, there's a set of mediocre not-very-supported -steps in the `wiki <https://gitorious.org/mediagoblin/pages/Home>`_. - - -.. _get-requirements-section: - -Getting requirements -==================== - -First, you need to have the following installed before you can build -an environment for hacking on GNU MediaGoblin: - -* Python 2.6 or 2.7 - http://www.python.org/ - - You'll need Python as well as the dev files for building modules. - -* python-lxml - http://lxml.de/ -* git - http://git-scm.com/ -* MongoDB - http://www.mongodb.org/ - -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 - -On Fedora:: - - yum install mongodb-server python-paste-deploy python-paste-script \ - git-core python python-devel python-lxml - -.. YouCanHelp:: - - If you have instructions for other GNU/Linux distributions to set - up requirements, let us know! - - -.. _hacking-with-buildout: - - -How to set up and maintain an environment for hacking with buildout -=================================================================== - -**Requirements** - -No additional requirements. - - -**Create a development environment** - -After installing the requirements, follow these steps: - -1. Clone the repository:: - - git clone git://gitorious.org/mediagoblin/mediagoblin.git - -2. Bootstrap and run buildout:: - - cd mediagoblin - python bootstrap.py && ./bin/buildout - - -That's it! Using this method, buildout should create a ``user_dev`` -directory, in which certain things will be stored (media, beaker -session stuff, etc). You can change this, but for development -purposes this default should be fine. - - -**Updating for dependency changes** - -While hacking on GNU MediaGoblin over time, you'll eventually have to -update your development environment because the dependencies have -changed. To do that, run:: - - ./bin/buildout && ./bin/gmg migrate - - -**Updating for code changes** - -You don't need to do anything---code changes are automatically -available. - - -**Deleting your buildout** - -At some point, you may want to delete your buildout. Perhaps it's to -start over. Perhaps it's to test building development environments -with buildout. - -To do this, do:: - - rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev - - -Running the server -================== - -If you want to get things running quickly and without hassle, just -run:: - - ./lazyserver.sh - -This will start up a python server where you can begin playing with -mediagoblin. It will also run celery in "always eager" mode so you -don't have to start a separate process for it. - -This is fine in development, but if you want to actually run celery -separately for testing (or deployment purposes), you'll want to run -the server independently:: - - ./bin/paster serve paste.ini --reload - - -Running celeryd -=============== - -If you aren't using ./lazyserver.sh or otherwise aren't running celery -in always eager mode, you'll need to do this if you want your media to -process and actually show up. It's probably a good idea in -development to have the web server (above) running in one terminal and -celeryd in another window. - -Run:: - - CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd - - -Running the test suite -====================== - -Run:: - - ./runtests.sh - - -Running a shell -=============== - -If you want a shell with your database pre-setup and an instantiated -application ready and at your fingertips.... - -Run:: - - ./bin/gmg shell - - -Troubleshooting -=============== - -pymongo.errors.AutoReconnect: could not find master/primary ------------------------------------------------------------ - -If you see this:: - - pymongo.errors.AutoReconnect: could not find master/primary - -then make sure mongodb is installed and running. - -If it's installed, check the mongodb log. On my machine, that's -``/var/log/mongodb/mongodb.log``. If you see something like:: - - old lock file: /var/lib/mongodb/mongod.lock. probably means... - -in that case you might have had an unclean shutdown. Try:: - - sudo mongod --repair - -If that didn't work, just delete the lock file and relaunch mongodb. - -Anyway, then start the mongodb server in whatever way is appropriate -for your distro / OS. - - -pkg_resources.DistributionNotFound: distribute ----------------------------------------------- - -If you get this while running buildout:: - - pkg_resources.DistributionNotFound: distribute - -Try this commmand instead:: - - python bootstrap.py --distribute && ./bin/buildout - - -Wiping your user data -===================== - -.. 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. - -.. YouCanHelp:: - - If you're familiar with MongoDB, we'd love to get a `script that - removes all the GNU MediaGoblin data from an existing instance - <http://bugs.foocorp.net/issues/296>`_. Let us know! - - -Quickstart for Django programmers -================================= - -We're not using Django, but the codebase is very Django-like in its -structure. - -* ``routing.py`` is like ``urls.py`` in Django -* ``models.py`` has mongokit ORM definitions -* ``views.py`` is where the views go - -We're using MongoDB. Basically, instead of a relational database with -tables, you have a big JSON structure which acts a lot like a Python -dict. - - -.. YouCanHelp:: - - If there are other things that you think would help orient someone - new to GNU MediaGoblin but coming from Django, let us know! - - -Bite-sized bugs to start with -============================= - -**May 3rd, 2011**: We don't have a list of bite-sized bugs, yet, but -this is important to us. If you're interested in things to work on, -let us know on `the mailing list <http://mediagoblin.org/join/>`_ or -on the `IRC channel <http://mediagoblin.org/join/>`_. - - -Tips for people new to coding -============================= - -Learning 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. - -.. YouCanHelp:: - - If you know of other good quality Python tutorials and Python - tutorial videos, let us know! - - -Learning Libraries GNU MediaGoblin uses ---------------------------------------- - -GNU MediaGoblin uses a variety of libraries in order to do what it -does. These libraries are listed in the :ref:`codebase-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. - - -.. _hacking-howto-git: - -Learning git ------------- - -git is an interesting and very powerful tool. Like all powerful -tools, it has a learning curve. - -If you're new to git, we highly recommend the following resources for -getting the hang of it: - -* `Learn Git <http://learn.github.com/p/intro.html>`_ --- the GitHub - intro to git -* `Pro Git <http://progit.org/book/>`_ --- fantastic book -* `Git casts <http://gitcasts.com/>`_ --- screencast covering git - usage -* `Git Reference <http://gitref.org/>`_ --- Git reference that makes - it easier to get the hang of git if you're coming from other version - control systems - -There's also a git mission at `OpenHatch <http://openhatch.org/>`_. - - -Learning other utilities ------------------------- - -The `OpenHatch <http://openhatch.org/>`_ site has a series of -`training missions <http://openhatch.org/missions/>`_ which are -designed to help you learn how to use these tools. - -If you're new to tar, diff, patch and git, we highly recommend you sign -up with OpenHatch and do the missions. diff --git a/docs/_static/placeholder b/docs/source/_static/placeholder index e69de29b..e69de29b 100644 --- a/docs/_static/placeholder +++ b/docs/source/_static/placeholder diff --git a/docs/source/_templates/mg_theme/layout.html b/docs/source/_templates/mg_theme/layout.html new file mode 100644 index 00000000..eccda14b --- /dev/null +++ b/docs/source/_templates/mg_theme/layout.html @@ -0,0 +1,39 @@ +{# + default/layout.html + ~~~~~~~~~~~~~~~~~~~ + + Sphinx layout template for the default theme. + + :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{% extends "basic/layout.html" %} + +{% if theme_collapsiblesidebar|tobool %} +{% set script_files = script_files + ['_static/sidebar.js'] %} +{% endif %} + +{%- block footer %} + <div class="footer"> + <div> + {% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %} + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {%- endif %} + {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %} + </div> +<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/88x31.png" /></a><br /><span xmlns:dc="http://purl.org/dc/elements/1.1/" href="http://purl.org/dc/dcmitype/Text" property="dc:title" rel="dc:type">{{ shorttitle|e }}</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="http://bluesock.org/~willg/" property="cc:attributionName" rel="cc:attributionURL">Will Kahn-Greene</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.<br /> + </div> + +<script type="text/javascript"> + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-163840-8']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); +</script> +{%- endblock %} diff --git a/docs/source/_templates/mg_theme/static/default.css_t b/docs/source/_templates/mg_theme/static/default.css_t new file mode 100644 index 00000000..f200a0fe --- /dev/null +++ b/docs/source/_templates/mg_theme/static/default.css_t @@ -0,0 +1,299 @@ +/* + * default.css_t + * ~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- default theme. + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: {{ theme_bodyfont }}; + font-size: 100%; + background-color: {{ theme_footerbgcolor }}; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: {{ theme_sidebarbgcolor }}; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: {{ theme_bgcolor }}; + color: {{ theme_textcolor }}; + padding: 0 20px 30px 20px; +} + +{%- if theme_rightsidebar|tobool %} +div.bodywrapper { + margin: 0 230px 0 0; +} +{%- endif %} + +div.footer { + color: {{ theme_footertextcolor }}; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: {{ theme_footertextcolor }}; + text-decoration: underline; +} + +div.related { + background-color: {{ theme_relbarbgcolor }}; + line-height: 30px; + color: {{ theme_relbartextcolor }}; +} + +div.related a { + color: {{ theme_relbarlinkcolor }}; +} + +div.sphinxsidebar { + {%- if theme_stickysidebar|tobool %} + top: 30px; + bottom: 0; + margin: 0; + position: fixed; + overflow: auto; + height: auto; + {%- endif %} + {%- if theme_rightsidebar|tobool %} + float: right; + {%- if theme_stickysidebar|tobool %} + right: 0; + {%- endif %} + {%- endif %} +} + +{%- if theme_stickysidebar|tobool %} +/* this is nice, but it it leads to hidden headings when jumping + to an anchor */ +/* +div.related { + position: fixed; +} + +div.documentwrapper { + margin-top: 30px; +} +*/ +{%- endif %} + +div.sphinxsidebar h3 { + font-family: {{ theme_headfont }}; + color: {{ theme_sidebartextcolor }}; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar h4 { + font-family: {{ theme_headfont }}; + color: {{ theme_sidebartextcolor }}; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar a { + color: {{ theme_sidebarlinkcolor }}; +} + +div.sphinxsidebar input { + border: 1px solid {{ theme_sidebarlinkcolor }}; + font-family: sans-serif; + font-size: 1em; +} + + +/* -- hyperlink styles ------------------------------------------------------ */ + +a { + color: {{ theme_linkcolor }}; + text-decoration: none; +} + +a:visited { + color: {{ theme_visitedlinkcolor }}; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +{% if theme_externalrefs|tobool %} +a.external { + text-decoration: none; + border-bottom: 1px dashed {{ theme_linkcolor }}; +} + +a.external:hover { + text-decoration: none; + border-bottom: none; +} +{% endif %} + +/* -- body styles ----------------------------------------------------------- */ + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: {{ theme_headfont }}; + background-color: {{ theme_headbgcolor }}; + font-weight: normal; + color: {{ theme_headtextcolor }}; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: {{ theme_headlinkcolor }}; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: {{ theme_headlinkcolor }}; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.admonition p { + margin-bottom: 5px; +} + +div.admonition pre { + margin-bottom: 5px; +} + +div.admonition ul, div.admonition ol { + margin-bottom: 5px; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: {{ theme_codebgcolor }}; + color: {{ theme_codetextcolor }}; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +th { + background-color: #ede; +} + +.warning tt { + background: #efc2c2; +} + +.note tt { + background: #d6d6d6; +} + +.viewcode-back { + font-family: {{ theme_bodyfont }}; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} diff --git a/docs/source/_templates/mg_theme/theme.conf b/docs/source/_templates/mg_theme/theme.conf new file mode 100644 index 00000000..49442e3b --- /dev/null +++ b/docs/source/_templates/mg_theme/theme.conf @@ -0,0 +1,31 @@ +[theme] +inherit = basic +stylesheet = default.css +pygments_style = sphinx + +[options] +rightsidebar = false +stickysidebar = false +collapsiblesidebar = false +externalrefs = false + +footerbgcolor = #b11818 +footertextcolor = #ffffff +sidebarbgcolor = #6a0000 +sidebartextcolor = #ffffff +sidebarlinkcolor = #98dbcc +relbarbgcolor = #b11818 +relbartextcolor = #ffffff +relbarlinkcolor = #ffffff +bgcolor = #ffffff +textcolor = #000000 +headbgcolor = #fdeded +headtextcolor = #20435c +headlinkcolor = #c60f0f +linkcolor = #355f7c +visitedlinkcolor = #355f7c +codebgcolor = #eeffcc +codetextcolor = #333333 + +bodyfont = sans-serif +headfont = 'Trebuchet MS', sans-serif diff --git a/docs/codebase.rst b/docs/source/codebase.rst index 898eadfe..ba5f1e46 100644 --- a/docs/codebase.rst +++ b/docs/source/codebase.rst @@ -21,7 +21,7 @@ various recipes for getting things done. for where we hang out. For more information on how to get started hacking on GNU MediaGoblin, -see :ref:`hacking-howto`. +see `the wiki <http://wiki.mediagoblin.org/>`_. Software Stack diff --git a/docs/conf.py b/docs/source/conf.py index 6c64cdda..e2f327c9 100644 --- a/docs/conf.py +++ b/docs/source/conf.py @@ -48,9 +48,9 @@ copyright = u'2011, Free Software Foundation, Inc and contributors' # built documents. # # The short X.Y version. -version = '0.0.3' +version = '0.0.4' # The full version, including alpha/beta/rc tags. -release = '0.0.3' +release = '0.0.4' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -64,7 +64,7 @@ release = '0.0.3' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] +exclude_patterns = ['_build', 'mgext', '_templates', '_static'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -214,3 +214,26 @@ man_pages = [ ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', [u'Chris Webber, et al'], 1) ] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', u'gnumediagoblin', + 'GNU MediaGoblin', 'Media sharing web application.', 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' diff --git a/docs/contributinghowto.rst b/docs/source/contributinghowto.rst index 06d2814e..a4f5771a 100644 --- a/docs/contributinghowto.rst +++ b/docs/source/contributinghowto.rst @@ -46,8 +46,8 @@ Here are some things you can do today: **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! + `wiki <http://wiki.mediagoblin.org/`_. We even have tips on + *becoming* a coder and we're willing to help you! **Send encouragement** @@ -135,7 +135,7 @@ the project, Chris Webber, will make a custom drawing of a goblin dedicated specifically to you. For why we're doing copyright assignment, see the -:ref:`design-decisions-chapter`. +`wiki <http://wiki.mediagoblin.org/>`_. .. _filing-bugs: diff --git a/docs/deploymenthowto.rst b/docs/source/deploymenthowto.rst index f50edfb6..f3093a60 100644 --- a/docs/deploymenthowto.rst +++ b/docs/source/deploymenthowto.rst @@ -12,5 +12,5 @@ Step 3: Write the deployment guide and profit! But seriously, this is a stub since we're not quite there (yet) but if you want to see where we are now, you can try to run the latest -development version by following the instructions at -:ref:`hacking-howto`. +development version by following the instructions on +`the wiki <http://wiki.mediagoblin.org/>`_. diff --git a/docs/foreword.rst b/docs/source/foreword.rst index 1d423f08..1d423f08 100644 --- a/docs/foreword.rst +++ b/docs/source/foreword.rst diff --git a/docs/git.rst b/docs/source/git.rst index bd0f9d52..ab3206b6 100644 --- a/docs/git.rst +++ b/docs/source/git.rst @@ -221,4 +221,4 @@ because he doesn't need it anymore. How to learn git ================ -Check out :ref:`hacking-howto-git`! +Check out `the wiki <http://wiki.mediagoblin.org/>`_. diff --git a/docs/goblin.png b/docs/source/goblin.png Binary files differindex e20265e6..e20265e6 100644 --- a/docs/goblin.png +++ b/docs/source/goblin.png diff --git a/docs/index.rst b/docs/source/index.rst index 2f84d6a6..8c00869a 100644 --- a/docs/index.rst +++ b/docs/source/index.rst @@ -15,11 +15,9 @@ Table of Contents: mediagoblin contributinghowto deploymenthowto - hackinghowto theminghowto git codebase - designdecisions vision diff --git a/docs/mediagoblin.rst b/docs/source/mediagoblin.rst index c437ecc3..af6658f3 100644 --- a/docs/mediagoblin.rst +++ b/docs/source/mediagoblin.rst @@ -30,9 +30,9 @@ Why are we doing this? Centralization and proprietization of media on the internet is a serious problem and makes the web go from a system of extreme resilience to a system of frightening fragility. We believe people -should be able to own their data and that means someone has to build -the tools to make it possible. We decided that in this case, that -someone would be us! +should be able to free their data from proprietary control and that +means someone has to build the tools to make it possible. We decided +that in this case, that someone would be us! Who are you? diff --git a/docs/mgext/__init__.py b/docs/source/mgext/__init__.py index e69de29b..e69de29b 100644 --- a/docs/mgext/__init__.py +++ b/docs/source/mgext/__init__.py diff --git a/docs/mgext/youcanhelp.py b/docs/source/mgext/youcanhelp.py index a99d0e4d..a99d0e4d 100644 --- a/docs/mgext/youcanhelp.py +++ b/docs/source/mgext/youcanhelp.py diff --git a/docs/snugglygoblin.png b/docs/source/snugglygoblin.png Binary files differindex f325ae4b..f325ae4b 100644 --- a/docs/snugglygoblin.png +++ b/docs/source/snugglygoblin.png diff --git a/docs/theminghowto.rst b/docs/source/theminghowto.rst index 7b40685f..7b40685f 100644 --- a/docs/theminghowto.rst +++ b/docs/source/theminghowto.rst diff --git a/docs/vision.rst b/docs/source/vision.rst index fad248df..fad248df 100644 --- a/docs/vision.rst +++ b/docs/source/vision.rst |
