Clean up documentation and add documentation on activities

6 files changed, 237 insertions, 63 deletions

diff --git a/docs/source/api/activities.rst b/docs/source/api/activities.rst
new file mode 100644
index 00000000..bd1b4152
--- /dev/null
+++ b/docs/source/api/activities.rst
@@ -0,0 +1,186 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+   
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+   
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+==========
+Activities
+==========
+
+.. contents:: Sections
+   :local:
+
+GNU MediaGoblin uses `Activity Streams 1.0 <http://activitystrea.ms>`_ JSON
+format to represent activities or events that happen. There are several
+components to Activity Streams.
+
+Objects
+-------
+These represent "things" in MediaGoblin such as types of media, comments, collections
+of other objects, etc. There are attributes all objects have and some attributes which
+are specific to certain objects.
+
+Example
+^^^^^^^
+a representation of an image object::
+
+    {
+        "id": "https://gmg.server.tld/api/image/someidhere",
+        "objectType": "image",
+        "content": "My lovely image",
+        "image": {
+            "url": "https://gmg.server.tld/mgoblin_media/media_entries/23/some_image.jpg",
+            "height": 1000,
+            "width": 500
+        },
+        "author": {
+            "id": "acct:someone@gmg.server.tld"
+        }
+    }
+
+This has both attributes which are on all objects (e.g. ``objectType`` and ``id``)
+and attributes which are on only images (e.g. ``image``).
+
+Activities
+----------
+This is something which happens such as: commenting on an image, uploading an image, etc.
+these always have a ``verb`` which describes what kind of activity it is and they always have
+an ``object`` associated with them.
+
+Example
+^^^^^^^
+A activity which describes the event of posting a new image::
+
+    {
+        "id": "https://gmg.server.tld/api/activity/someidhere",
+        "verb": "post",
+        "object": {
+            "id": "https://gmg.server.tld/api/comment/someid",
+            "objectType": "comment",
+            "content": "What a wonderful picture you have there!",
+            "inReplyTo": {
+                "id": "https://gmg.server.tld/api/image/someidhere"
+            }
+        },
+        "author": {
+            "id": "acct:someone@gmg.server.tld"
+        }
+    }
+
+Collections
+-----------
+These are ordered lists which contain objects. Currently in GNU MediaGoblin they are used
+to represent "albums" or collections of media however they can represent anything. They will
+be used in the future to represent lists/groups of users which you can send activities to.
+
+Example
+^^^^^^^
+A collection which contains two images::
+
+    {
+        "id": "https://gmg.server.tld/api/collection/someidhere",
+        "totalItems": 2,
+        "url": "http://gmg.server.tld/u/someone/collection/cool-album/",
+        "items": [
+			{
+			   "id": "https://gmg.server.tld/api/image/someidhere",
+			   "objectType": "image",
+			   "content": "My lovely image",
+			   "image": {
+			       "url": "https://gmg.server.tld/mgoblin_media/media_entries/23/some_image.jpg",
+			       "height": 1000,
+			       "width": 500
+			   },
+			   "author": {
+			       "id": "acct:someone@gmg.server.tld"
+			   }
+			},
+			{
+			   "id": "https://gmg.server.tld/api/image/someother",
+			   "objectType": "image",
+			   "content": "Another image for you",
+			   "image": {
+			       "url": "https://gmg.server.tld/mgoblin_media/media_entries/24/some_other_image.jpg",
+			       "height": 1000,
+			       "width": 500
+			   },
+			   "author": {
+			       "id": "acct:someone@gmg.server.tld"
+			   }
+			}
+        ]
+    }
+
+Feeds
+=====
+
+There are several feeds which can be read and posted to as part of the API. Some
+of the feeds are still a work in progress however a lot of them are present for
+compatibility.
+
+Inbox
+-----
+
+**Endpoint:** `/api/user/<username>/inbox`
+
+This feed can be read by user to see what media has been sent to them.
+MediaGoblin currently doesn't have the ability to sent media to anyone
+as all media is public, all media on that instance should show up in the
+users inbox.
+
+There are also subsets of the inbox which are:
+
+Major
+^^^^^
+**Endpoint:** ``/api/user/<username>/inbox/major``
+
+This contains all major changes such as new objects being posted. Currently
+comments exist in this feed, in the future they will be moved to the minor feed.
+
+Minor
+^^^^^
+**Endpoint:** ``/api/user/<username>/inbox/minor``
+
+This contains minor changes such as objects being updated or deleted. This feed
+should have comments in it, currently they are listed under major, in the future
+they will exist in this endpoint.
+
+Direct
+^^^^^^
+**Endpoint:** ``/api/user/<username>/inbox/direct``
+
+Currently this is just a mirror of the regular inbox for compatibility with
+pump.io. In the future this will contain all objects specifically addressed to
+the user.
+
+Direct major
+^^^^^^^^^^^^
+**Endpoint:** ``/api/user/<username>/inbox/direct/major``
+
+Currently this is just a mirror of the major inbox for compatibility with
+pump.io. In the future this will contain all major activities which are
+specifically addressed to the user.
+
+Direct minor
+^^^^^^^^^^^^
+**Endpoint:** ``/api/user/<username>/inbox/direct/minor``
+
+Currently this is just a mirror of the minor inbox for compatibility with
+pump.io. In the future this will contain all minor activities which are
+specifically addressed to the user.
+
+Feed (outbox)
+-------------
+**Endpoint:** ``/api/user/<username>/feed``
+
+This is where the client should post new activities. It can be read by the
+user to see what they have posted. This will only contain content they have
+authored or shared (sharing will come in the future).
diff --git a/docs/source/api/client_register.rst b/docs/source/api/authentication.rst
index 9c29bafc..1fc541fd 100644
--- a/docs/source/api/client_register.rst
+++ b/docs/source/api/authentication.rst
@@ -11,7 +11,13 @@
    Dedication along with this software. If not, see
    <http://creativecommons.org/publicdomain/zero/1.0/>.
 
-====================
+==================
+API Authentication
+==================
+
+.. contents:: Sections
+   :local:
+
 Registering a Client
 ====================
 
@@ -31,7 +37,7 @@ client_secret
     **update only** - This should only be used updating client information, this is the client_secret given when you register
 
 contacts
-    **optional** - This a space seporated list of email addresses to contact of people responsible for the client
+    **optional** - This a space separated list of email addresses to contact of people responsible for the client
 
 application_type
     **required** - This is the type of client you are making, this must be either *web* or *native*
@@ -43,11 +49,11 @@ logo_uri
     **optional** - This is a URI of the logo image for your client
 
 redirect_uri
-    **optional** - This is a space seporated list of pre-registered URLs for use at the Authorization Server
+    **optional** - This is a space separated list of pre-registered URLs for use at the Authentication Server
 
 
 Response
---------
+^^^^^^^^
 
 You will get back a response:
 
@@ -60,12 +66,11 @@ client_secret
 expires_at
     This is time that the client credentials expire. If this is 0 the client registration does not expire.
 
-=======
-Example
-=======
+Examples
+--------
 
 Register Client
----------------
+^^^^^^^^^^^^^^^
 
 To register a client for the first time, this is the minimum you must supply::
 
@@ -84,7 +89,7 @@ A Response will look like::
 
 
 Updating Client
----------------
+^^^^^^^^^^^^^^^
 
 Using the response we got above we can update the information and add new information we may have opted not to supply::
 
@@ -107,9 +112,8 @@ The response will just return back the client_id and client_secret you sent::
     }
 
 
-======
-Errors
-======
+Possible Registration Errors
+----------------------------
 
 There are a number of errors you could get back, This explains what could cause some of them:
 
@@ -129,7 +133,7 @@ client_id is required to update.
     When you try and update you need to specify the client_id, this will be what you were given when you initially registered the client.
 
 client_secret is required to update.
-    When you try to update you need to specify the client_secrer, this will be what you were given when you initially register the client.
+    When you try to update you need to specify the client_secret, this will be what you were given when you initially register the client.
 
 Unauthorized.
     This is when you are trying to update however the client_id and/or client_secret you have submitted are incorrect.
@@ -144,14 +148,34 @@ Logo URL <url> is not a valid URL
     This is when the URL specified did not meet the validation.
 
 contacts must be a string of space-separated email addresses.
-    ``contacts`` should be a string (not a list), ensure each email is seporated by a space
+    ``contacts`` should be a string (not a list), ensure each email is separated by a space
 
 Email <email> is not a valid email
     This is when you have submitted an invalid email address
 
 redirect_uris must be space-separated URLs.
-    ``redirect_uris`` should be a string (not a list), ensure each URL is seporated by a space
+    ``redirect_uris`` should be a string (not a list), ensure each URL is separated by a space
 
 URI <URI> is not a valid URI
     This is when your URI is invalid.
 
+OAuth
+=====
+
+GNU MediaGoblin uses OAuth1 to authenticate requests to the API. There are many
+libraries out there for OAuth1, you're likely not going to have to do much. There
+is a library for the GNU MediaGoblin called `PyPump <https://github.com/xray7224/PyPump>`_.
+We are not using OAuth2 as we want to stay completely compatible with pump.io.
+
+
+Endpoints
+---------
+
+These are the endpoints you need to use for the oauth requests:
+
+`/oauth/request_token` is for getting the request token.
+
+`/oauth/authorize` is to send the user to to authorize your application.
+
+`/oauth/access_token` is for getting the access token to use in requests.
+
diff --git a/docs/source/api/media.rst b/docs/source/api/media.rst
index bafe43d3..3e0b4391 100644
--- a/docs/source/api/media.rst
+++ b/docs/source/api/media.rst
@@ -13,19 +13,19 @@
 
 .. info:: Currently only image uploading is supported.
 
-===============
-Uploading Media
-===============
+=====
+Media
+=====
 
 To use any the APIs mentioned in this document you will required :doc:`oauth`
 
-Uploading and posting an media requiest you to make two to three requests:
+Uploading and posting an media request you to make two to three requests:
 
 1) Uploads the data to the server
 2) Post media to feed
 3) Update media to have title, description, license, etc. (optional)
 
-These steps could be condenced in the future however currently this is how the
+These steps could be recondensed in the future however currently this is how the
 pump.io API works. There is currently an issue open, if you would like to change
 how this works please contribute upstream: https://github.com/e14n/pump.io/issues/657
 
@@ -41,7 +41,7 @@ A POST request should be made to the media upload URI submitting at least two he
 * `Content-Length` - size in bytes of the media.
 
 The media data should be submitted as POST data to the image upload URI.
-You will get back a JSON encoded response which will look similiar to::
+You will get back a JSON encoded response which will look similar to::
 
     {
         "updated": "2014-01-11T09:45:48Z",
@@ -139,7 +139,7 @@ and update request to the endpoint, the following attributes can be submitted:
 .. note:: license attribute is mediagoblin specific, pump.io does not support this attribute
 
 
-The update request should look something similiar to::
+The update request should look something similar to::
 
     {
         "verb": "update",
diff --git a/docs/source/api/media_interaction.rst b/docs/source/api/media_interaction.rst
index 41114a71..2c244845 100644
--- a/docs/source/api/media_interaction.rst
+++ b/docs/source/api/media_interaction.rst
@@ -12,7 +12,7 @@
    <http://creativecommons.org/publicdomain/zero/1.0/>.
 
 Pump.io supports a number of different interactions that can happen against
-media. Theser are commenting, liking/favoriting and (re-)sharing. Currently
+media. These are commenting, liking/favoriting and (re-)sharing. Currently
 MediaGoblin supports just commenting although other interactions will come at
 a later date.
 
@@ -23,7 +23,7 @@ How to comment
 .. warning:: Commenting on a comment currently is NOT supported.
 
 Commenting is done by posting a comment activity to the users feed. The
-activity should look similiar to::
+activity should look similar to::
 
     {
         "verb": "post",
diff --git a/docs/source/api/oauth.rst b/docs/source/api/oauth.rst
deleted file mode 100644
index 003ad492..00000000
--- a/docs/source/api/oauth.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-.. MediaGoblin Documentation
-
-   Written in 2011, 2012 by MediaGoblin contributors
-
-   To the extent possible under law, the author(s) have dedicated all
-   copyright and related and neighboring rights to this software to
-   the public domain worldwide. This software is distributed without
-   any warranty.
-
-   You should have received a copy of the CC0 Public Domain
-   Dedication along with this software. If not, see
-   <http://creativecommons.org/publicdomain/zero/1.0/>.
-
-==============
-Authentication
-==============
-
-GNU MediaGoblin uses OAuth1 to authenticate requests to the API. There are many
-libraries out there for OAuth1, you're likely not going to have to do much. There
-is a library for the GNU MediaGoblin called `PyPump <https://github.com/xray7224/PyPump>`_.
-We are not using OAuth2 as we want to stay completely compatable with GNU MediaGoblin.
-
-
-We use :doc:`client_register` to get the client ID and secret.
-
-Endpoints
----------
-
-These are the endpoints you need to use for the oauth requests:
-
-`/oauth/request_token` is for getting the request token.
-
-`/oauth/authorize` is to send the user to to authorize your application.
-
-`/oauth/access_token` is for getting the access token to use in requests.
-
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 8e49d1d1..97e67bd0 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -105,13 +105,13 @@ This chapter covers MediaGoblin's `Pump API
 work in progress; full federation is not supported at the moment, but
 media uploading works!  You can use something like
 `PyPump <http://pypump.org>`_
-to write MediaGoblin uploadable applications.)
+to write MediaGoblin applications.)
 
 .. toctree::
    :maxdepth: 1
 
-   api/client_register
-   api/oauth
+   api/authentication
+   api/activities
    api/media
    api/media_interaction