heckyel/mediagoblin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Overhauls docs

Browse Source 
* Removes a bunch of content that doesn't need to be in the suer manual
  anymore.
* Fixes issues so it's more readable in source form.
* Adds help chapter.
* Moves links out of paragraphs to reduce line length.
* Cleans up some language.
* Fixes some links.
This commit is contained in:
Will Kahn-Greene 2011-10-05 23:08:53 -04:00
parent c0022ecc88
commit 917d4663af
9 changed files with 82 additions and 433 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/source/about_mediagoblin.rst → docs/source/about.rst
View File

@ -1,6 +1,6 @@
================= =======================
GNU MediaGoblin About GNU MediaGoblin
================= =======================
.. contents:: Sections .. contents:: Sections
:local: :local:
@ -9,55 +9,63 @@
What is GNU MediaGoblin What is GNU MediaGoblin
======================= =======================
In 2008 a number of free software developers and activists gathered at In 2008, a number of free software developers and activists gathered
the FSF to attempt to answer the question "What should software at the FSF to attempt to answer the question "What should software
freedom look like on the participatory web?" Their answer, the freedom look like on the participatory web?" Their answer, the
`Franklin Street Statement <http://autonomo.us/2008/07/franklin-street-statement/>`_, `Franklin Street Statement`_ has lead to the development of
has lead to the development of `autonomo.us <http://autonomo.us/>`_ `autonomo.us`_ community, and free software projects including
community, and free software projects including `Identi.ca <http://identi.ca/>`_ `Identi.ca`_ and `Libre.fm`_.
and `Libre.fm <http://libre.fm/>`_.
.. _Franklin Street Statement: http://autonomo.us/2008/07/franklin-street-statement/
.. _autonomo.us: http://autonomo.us/
.. _identi.ca: http://identi.ca/
.. _Libre.fm: http://libre.fm/
Identi.ca and Libre.fm address the need for micro-blogging and music Identi.ca and Libre.fm address the need for micro-blogging and music
sharing services and software that respect users' freedom and sharing services and software that respect users' freedom and
autonomy. GNU MediaGoblin emerges from this milieu to create a autonomy. GNU MediaGoblin emerges from this milieu to create a
platform for us to share photos in an environment that respects our platform for us to share photos in an environment that respects our
freedom and independence. In the future MediaGoblin will include freedom and independence. In the future MediaGoblin will include
support other media, like video, and provide tools to facilitate support other media, like video, and provide tools to facilitate
collaboration on media projects. collaboration on media projects.
Why Build GNU MediaGoblin Why Build GNU MediaGoblin
========================= =========================
The Internet is designed--and works best--as a complex and endlessly The Internet is designed---and works best---as a complex and endlessly
resilient network. When key services and media outlets are resilient network. When key services and media outlets are
concentrated in centralized platforms, the network becomes less useful concentrated in centralized platforms, the network becomes less useful
and increasingly fragile. As always, the proprietary nature of these and increasingly fragile. As always, the proprietary nature of these
systems, hinders users ability to develop, extend, and understand systems, hinders users ability to develop, extend, and understand
their software; however, in the case of network services it also means their software; however, in the case of network services it also means
that users must forfeit control of their data to the service that users must forfeit control of their data to the service
providers. providers.
Therefore, we believe that network services must be federated to avoid Therefore, we believe that network services must be federated to avoid
centralization and that everyone ought to have control over their centralization and that everyone ought to have control over their
data. In support of this, we've decided to help build the tools to data. In support of this, we've decided to help build the tools to
make these kinds of services possible. We hope you'll join us, both as make these kinds of services possible. We hope you'll join us, both
users and as contributors. as users and as contributors.
Who Contributes to the Project Who Contributes to the Project
============================== ==============================
You do! You do!
We are free software activists and folks who have worked on a variety We are free software activists and folks who have worked on a variety
of other projects including: Libre.fm, GNU Social, Status.net, Miro, of other projects including: Libre.fm, GNU Social, Status.net, Miro,
Miro Community, and OpenHatch among others. We're programmers, Miro Community, and OpenHatch among others. We're programmers,
musicians, writers, and painters. We're friendly and dedicated to musicians, writers, and painters. We're friendly and dedicated to
software and network freedom. software and network freedom.
How Can I Participate? How Can I Participate?
====================== ======================
See `Get Involved <http://mediagoblin.org/join/>`_ on the website.. See `Get Involved <http://mediagoblin.org/join/>`_ on the website. We
eagerly look forward to seeing you!
How is GNU MediaGoblin licensed? How is GNU MediaGoblin licensed?
@ -65,7 +73,7 @@ How is GNU MediaGoblin licensed?
GNU MediaGoblin software is released under an AGPLv3 license. GNU MediaGoblin software is released under an AGPLv3 license.
See the ``COPYING`` file in the source repository for details. See the ``COPYING`` file in the root of the source for details.
Is MedaGobilin an official GNU project? What does that mean? Is MedaGobilin an official GNU project? What does that mean?
@ -73,7 +81,8 @@ Is MedaGobilin an official GNU project? What does that mean?
MediaGoblin is an official GNU project! This status means that we the MediaGoblin is an official GNU project! This status means that we the
meet the GNU Project's rigorous standards for free software. To find meet the GNU Project's rigorous standards for free software. To find
out more about what that means, check out `the GNU site <http://gnu.org/>`_. out more about what that means, check out the `GNU website`_.
Please feel free to contact us with further questions! Please feel free to contact us with further questions!
.. _GNU website: http://gnu.org/

21
docs/source/codebase.rst
View File

@ -45,7 +45,7 @@ Software Stack
* Web application * Web application
* `Paste Deploy <http://pythonpaste.org/deploy/>`_ and * `Paste Deploy <http://pythonpaste.org/deploy/>`_ and
`Paste Script <http://pythonpaste.org/script/>`_: we'll use this for `Paste Script <http://pythonpaste.org/script/>`_: we'll use this for
configuring and launching the application configuring and launching the application
@ -83,22 +83,21 @@ After you've run buildout, you're faced with the following directory
tree:: tree::
mediagoblin/ mediagoblin/
|- mediagoblin/ #source code |- mediagoblin/ # source code
| |- tests/ | |- tests/
| |- templates/ | |- templates/
| |- auth/ | |- auth/
| \- submit/ | \- submit/
|- docs/ #documentation |- docs/ # documentation
| |
| #the below directories are generated by | # the below directories are generated by buildout.
| #buildout.
| |
|- bin/ #scripts |- bin/ # scripts
|- develop-eggs/ |- develop-eggs/
|- eggs/ |- eggs/
|- mediagoblin.egg-info/ |- mediagoblin.egg-info/
|- parts/ |- parts/
|- user_dev/ #sessions, etc |- user_dev/ # sessions, etc
As you can see, all the code for GNU MediaGoblin is in the As you can see, all the code for GNU MediaGoblin is in the
@ -108,7 +107,7 @@ Here are some interesting files and what they do:
:routing.py: maps url paths to views :routing.py: maps url paths to views
:views.py: views handle http requests :views.py: views handle http requests
:models.py: holds the mongodb schemas---these are the data structures :models.py: holds the mongodb schemas---these are the data structures
we're working with we're working with
You'll notice that there are several sub-directories: tests, You'll notice that there are several sub-directories: tests,
@ -122,9 +121,3 @@ templates, auth, submit, ...
and media item submission. If you look in these directories, you'll and media item submission. If you look in these directories, you'll
see they have their own ``routing.py``, ``view.py``, and see they have their own ``routing.py``, ``view.py``, and
``models.py`` in addition to some other code. ``models.py`` in addition to some other code.
Recipes
=======
FIXME - write this

215
docs/source/contributinghowto.rst
View File

@ -1,215 +0,0 @@
.. _contributing-howto-chapter:
===================================
HOWTO Contribute to GNU MediaGoblin
===================================
.. contents:: Sections
:local:
.. _join-the-community-section:
Join the community!
===================
We're **really** glad that you want to join the MediaGoblin community!
There are a variety of ways to help and support MediaGoblin and to
join the team. If you want to code, great, if not, even better!
MediaGoblin interested contributors in many different roles: users,
system administrators, technical writers, testers, evangelists,
UI/UX and graphics designers, cheerleaders, and dreamers.
This document provides an overview of different ways you can get
involved with MediaGoblin along with instructions for getting
started. There is some obvious overlap with `the "join" page on
mediagoblin.org <http://mediagoblin.org/pages/join.html>`_ at present.
Hang out with the MediaGoblin folk
----------------------------------
MediaGoblin has a `discussion listserv <http://lists.mediagoblin.org/listinfo/devel>`_,
and an IRC (``#mediagoblin``) channel on `freenode.net <http://freenode.com>`_.
Don't be afraid to drop by and say "Hi!" And, if you're looking for
something to do, just ask: there's always work to be done.
File Bugs / Triage Bugs
-----------------------
Issue reports are critical for all projects. Identified bugs give
developers a basis for beginning work, and providing an idea of what
features and issues are most important to users and the overall
usability of the software. If you identify errors, flaws, unexpected
behaviors, or deficits that impede use, file a bug.
See the section on `filing bugs <#filing-bugs>`_ for more information on how to file the best
and most useful bug reports.
If you want to contribute to MediaGoblin and don't know where to
start, look at the `bug database <http://bugs.foocorp.net/projects/mediagoblin/issues>`_
as a starting point.
See the section on `bug triage <#triage-bugs>`_ for suggestions on how
to most effectively triage and approach the issue queue.
Write/Fix Code
--------------
If you are a coder and you would like to write code, the `repository <https://gitorious.org/mediagoblin>`_
is hosted on `gitorious <https://gitorious.org/>`_. Clone or fork the
repository and start poking around. Become familiar with this `manual </>`_
for an overview of how the software works and is used. Consider the
`contributor wiki <http://wiki.mediagoblin.org/>`_ for more
information about the project, our preferred methods, and guides for
developing MediaGoblin. We even have tips on *becoming* a coder and
we're willing to help!
Send Encouragement, Spread the Word
-----------------------------------
Sometimes, a nice word, simple encouragement, and interest in the work
we're doing is enough to inspire a tizzy of productive work. Just a
bit more interest and encouragement can even make the difference
between a complete feature and limited functionality; between a
completed milestone and lost momentum.
Similarly, MediaGoblin, and the movement for free network services, is
always in need of encouragement. Use free network services, understand
the `principals <http://autonomo.us/2008/07/franklin-street-statement/>`_
behind the movement, be able to articulate the benefits of free
network services and the problems with psudo-free applications that
don't respect the users' freedom.
Write a blog post, post a status update, drop by the `listserv <http://mediagoblin.org/join/>`_
or join ``#mediagoblin`` on freenode.net and let us know.
Participate in MediaGoblin
==========================
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:
Become a User
-------------
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 Others
-----------
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 MediaGoblin 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
the `Deployment HOWTO </deploymenthowto.html>`_
.. _translating:
Translate MediaGoblin
---------------------
If you know English and another language and feel comfortable
translating elements of the interface or even the documentation,
we'd love to have help translating the software and resources.
Create a Theme
--------------
MedaGoblin development is premised on the idea that the entire
interface for the platform be completely theme-able. If you have a
design or theming background, consider developing themes for
MediaGoblin. New themes help test the theming system, provide
attractive and appealing interfaces for prospective users. If you want
to start a new theme but don't know where to start, touch base with
the development community on the list or in the IRC channel for more
information.
.. _filing-bugs:
File Bugs
=========
MediaGoblin uses a bug tracker called `Redmine <http://www.redmine.org>`_.
Our instance is located at `<http://bugs.foocorp.net/projects/mediagoblin>`_.
The most useful bug reports have the following components:
1. A short summary that's 60 characters or less.
2. A description that describes the issue (bug, feature request, ...)
as well as the context. Consider:
* If you think you've found a bug, can you reproduce it in a
controlled environment? Is the issue specific to a browser,
computer, image, media type, or other dimension? All data helps.
* If you're submitting a feature request, are there related links
on the Internet for more information? Would you be willing to
help implement or test the feature?
That's it!
The better the issue report, the easier it is to address the bug, and
the more likely that the developers will be able to resolve the
issue. If someone has questions about the bug report, they may reach
out to the reporter directly.
If you get a response after a couple of weeks, find someone on IRC.
.. _triage-bugs:
Triage Bugs
===========
The triage process involves reviewing bugs, removing duplicates,
validating that the issues described are reproducible, ensuring that
the exact behavior is properly documented, diagnosing the cause of
each issue, and working with developers to ensure that critical bugs
get addressed. In many cases, developers do this kind of work as a
matter of course, but one need not be able to code in order to help
working with bugs.
To triage bugs, go to the `bug tracker <http://bugs.foocorp.net/projects/mediagoblin>`_
and begin reviewing the open issues. If you are able, attempt to:
- ensure that one or two people in addition to the initial reporter
have been able to reproduce the issue.
- document the issue more clearly. If you had any trouble reproducing
the issue, provide any elucidating information that you can to help
others solve the problem more effectively.
- find a way to resolve the problem or provide a workaround.
For help, instructions, and suggestions be in touch with the
development community on the list or in the IRC channel for more
information. With many eyes, all bugs are shallow.
How to Get Help with MediaGoblin
================================
The usual channels, the IRC channel, the listserv, the bug tracker,
are all great ways to be in touch with us. Check the `web site <http://mediagoblin.org/pages/join.html>`_
for more specific contact information.

8
docs/source/deploymenthowto.rst → docs/source/deploying.rst
View File

@ -1,8 +1,8 @@
.. _deployment-howto: .. _deployment-chapter:
================== =======================
Deployment HOWTO Deploying MediaGoblin
================== =======================
Step 1: Write code that can be deployed. Step 1: Write code that can be deployed.

37
docs/source/foreword.rst
View File

@ -5,25 +5,15 @@ Foreword
About the MediaGoblin Manual About the MediaGoblin Manual
============================ ============================
Welcome to the GNU MediaGoblin manual. This document targets several This is the user manual for MediaGoblin. It covers how to set up and
classes of users, including: configure MediaGoblin and the kind of information that someone running
MediaGoblin would need to know.
* users who would like to try the software locally, We have other documentation at:
* systems administrators who want to deploy and administer the
software in "production environments," and
* anyone who wants to learn how MediaGoblin works.
Some information relevant to the MediaGoblin community members, * http://mediagoblin.org/join/ for general "join us" information
including how to get involved (We want and love contributors!) To join
as a contributor please see the following pages:
* http://mediagoblin.org/pages/join.html for general "join us" information
* http://wiki.mediagoblin.org/ for our contributor-focused wiki * http://wiki.mediagoblin.org/ for our contributor-focused wiki
If you suspect that documentation on http://docs.mediagoblin.org is
out of date, it might be. The documentation is updated regularly and
the "living" version of this resource resides in the ``mediagoblin``
repository with the project's source code the ``docs/`` directory.
Improving the MediaGobiin Manual Improving the MediaGobiin Manual
================================ ================================
@ -31,16 +21,15 @@ Improving the MediaGobiin Manual
There are a few ways---please pick whichever method is convenient for There are a few ways---please pick whichever method is convenient for
you! you!
1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/projects/mediagoblin/issues 1. Write up a bug report in the bug tracker
2. Tell someone on IRC ``#mediagoblin`` on Freenode. 2. Tell someone on IRC ``#mediagoblin`` on Freenode.
3. Send an email to Will ``willg at bluesock dot org``, or Sam at 3. Write an email to the devel mailing list.
``sam@cyborginstitute.com``
When you tell us about your issue, please let us know: Information about the bugtracker, IRC and the mailing list is all on
the `join page`_.
* where you are looking (in git? url of the web-page?) .. _join page: http://mediagoblin.org/join/
* what the issue is, and
* your thoughts on how to resolve it. Patches are the most helpful, but even feedback on what you think
could be improved and how to improve it is also helpful.
We hope these materials are useful and we look forward to any and all
feedback.

16
docs/source/help.rst Normal file
View File

@ -0,0 +1,16 @@
==================================
How to Get Help with MediaGoblin
==================================
There are a couple of ways to get help with problems with MediaGoblin:
1. ask for help on IRC
2. ask for help on the devel mailing list
Details for both IRC and the mailing list are on the `join page`_ of the
website.
.. _join page: http://mediagoblin.org/join/

9
docs/source/index.rst
View File

@ -12,12 +12,11 @@ Table of Contents:
:maxdepth: 2 :maxdepth: 2
foreword foreword
about_mediagoblin about
deploymenthowto deploying
theminghowto help
contributinghowto theming
codebase codebase
vision
Indices and tables Indices and tables

8
docs/source/theminghowto.rst → docs/source/theming.rst
View File

@ -1,8 +1,8 @@
.. _theming-howto: .. _theming-chapter:
=============== =====================
Theming HOWTO Theming MediaGoblin
=============== =====================
We haven't implemented the necessary scaffolding to allow for theming We haven't implemented the necessary scaffolding to allow for theming
yet. Thus, this chapter is a stub. yet. Thus, this chapter is a stub.

142
docs/source/vision.rst
View File

@ -1,142 +0,0 @@
=========================================
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 <http://jinja.pocoo.org/docs/>`_ we can just set up
user-overriding directories.
We'll also figure out some sort of way to provide theming "packages",
eventually.