Merge pull request #30 from sushimustwrite/master

added config, plugin, and library directories #27 #25 #23
photo · Jun 4, 2013 · b6c3f4f · b6c3f4f
2 parents 587a01f + 86ab5cc
commit b6c3f4f
Show file tree

Hide file tree

Showing 6 changed files with 249 additions and 0 deletions.
diff --git a/docs/Readme.markdown b/docs/Readme.markdown
@@ -3,3 +3,6 @@ OpenPhoto / Documentation
 
 You can find the documentation at http://theopenphotoproject.org/documentation. It's a mirror of what is here but easier to follow.
 
+If you'd like to contribute to the documentation, please do! We welcome any and all contributions. Fork this repository (documentation) and add your contribution, then send a pull request. The docs/contribute/documentation.markdown in this repository explains everything you need to more.
+
+Questions? We're here to help. Email our mailing list at [email protected] or ask in #openphoto on Freenode.
diff --git a/docs/configs/readme.markdown b/docs/configs/readme.markdown
@@ -0,0 +1,3 @@
+Your Trovebox installation comes with a number of configuration files and settings. This section explains the settings and what you can set them to.
+
+Questions? We can help. Send us an email at [email protected] or ask in #openphoto on Freenode.
diff --git a/docs/libraries/php.markdown b/docs/libraries/php.markdown
@@ -0,0 +1,97 @@
+Open Photo API / PHP Library
+=======================
+#### OpenPhoto, a photo service for the masses
+
+----------------------------------------
+
+<a name="php"></a>
+### How to use the library
+
+To use the library you need to first include `OpenPhotoOAuth.php`, then instantiate an instance of the class and start making calls.
+
+    include 'OpenPhotoOAuth.php';
+    $client = new OpenPhotoOAuth($host, $consumerKey, $consumerSecret, $token, $tokenSecret);
+    $resp = $client->get('/photos/list.json');
+    $resp = $client->post('/photo/62/update.json', array('tags' => 'tag1,tag2'));
+
+----------------------------------------
+
+<a name="cli"></a>
+### Using from the command line
+
+Make sure that the `openphoto` file is executable.
+
+    chown o+x openphoto
+
+You'll then want to export your secrets to the environment.
+We suggest putting them in a file and sourcing it prior to running `openphoto` commands.
+<a href="#credentials">Click here for instructions on getting credentials</a>.
+
+    # env.sh
+    export consumerKey=your_consumer_key
+    export consumerSecret=your_consumer_secret
+    export token=your_access_token
+    export tokenSecret=your_access_token_secret
+
+You'll need to source that file once for each terminal session.
+
+    source env.sh
+
+These are the options you can pass to the shell program.
+
+    -h hostname # default=localhost
+    -e endpoint # default=/photos/list.json
+    -X method # default=GET
+    -F params # i.e. -F 'title=my title' -F 'tags=mytag1,mytag1'
+    -p # pretty print the json
+    -v # verbose output
+    --encode # base 64 encode the photo
+
+Now you can run commands to the OpenPhoto API from your shell!
+
+    ./openphoto -h current.openphoto.me -p -e /photo/62/view.json -F 'returnSizes=20x20'
+    {
+      "message" : "Photo 62",
+      "code" : 200,
+      "result" : {
+        "tags" : [
+          
+        ],
+        "id" : "62",
+        "appId" : "current.openphoto.me",
+        "pathBase" : "\/base\/201108\/1312956581-opmeqViHrD.jpg",
+        "dateUploadedMonth" : "08",
+        "dateTakenMonth" : "08",
+        "exifCameraMake" : "",
+        "dateTaken" : "1312956581",
+        "title" : "Tomorrowland Main Stage 2011",
+        "height" : "968",
+        "description" : "",
+        "creativeCommons" : "BY-NC",
+        "dateTakenYear" : "2011",
+        "dateUploadedDay" : "09",
+        "longitude" : "4",
+        "host" : "opmecurrent.s3.amazonaws.com",
+        "hash" : "0455675a8c42148238b81ed1d8db655c45ae055a",
+        "status" : "1",
+        "width" : "1296",
+        "dateTakenDay" : "09",
+        "permission" : "1",
+        "pathOriginal" : "\/original\/201108\/1312956581-opmeqViHrD.jpg",
+        "size" : "325",
+        "dateUploadedYear" : "2011",
+        "views" : "0",
+        "latitude" : "50.8333",
+        "dateUploaded" : "1312956583",
+        "exifCameraModel" : "",
+        "Name" : "62",
+        "path20x20" : "http:\/\/current.openphoto.me\/photo\/62\/create\/ceb90\/20x20.jpg"
+      }
+    }
+
+<a name="credentials"></a>
+#### Getting your credentials
+
+You can get your credentals by clicking on the arrow next to your email address once you're logged into your site and then clicking on settings.
+If you don't have any credentials then you can create one for yourself by going to `/v1/oauth/flow`.
+Once completed go back to the settings page and you should see the credential you just created
diff --git a/docs/libraries/python.markdown b/docs/libraries/python.markdown
@@ -0,0 +1,131 @@
+Open Photo API / Python Library
+=======================
+#### OpenPhoto, a photo service for the masses
+[![Build Status](https://api.travis-ci.org/photo/openphoto-python.png)](https://travis-ci.org/photo/openphoto-python)
+
+----------------------------------------
+<a name="install"></a>
+### Installation
+    python setup.py install
+
+----------------------------------------
+<a name="credentials"></a>
+### Credentials
+
+For full access to your photos, you need to create the following config file in ``~/.config/openphoto/default``
+
+    # ~/.config/openphoto/default
+    host = your.host.com
+    consumerKey = your_consumer_key
+    consumerSecret = your_consumer_secret
+    token = your_access_token
+    tokenSecret = your_access_token_secret
+
+The ``config_file`` switch lets you specify a different config file.
+
+To get your credentials:
+ * Log into your Trovebox site
+ * Click the arrow on the top-right and select 'Settings'
+ * Click the 'Create a new app' button
+ * Click the 'View' link beside the newly created app
+
+----------------------------------------
+<a name="python"></a>
+### How to use the library
+
+You can use the library in one of two ways:
+
+ * Direct GET/POST calls to the server
+ * Access via Python classes/methods
+
+<a name="get_post"></a>
+#### Direct GET/POST:
+
+    from openphoto import OpenPhoto
+    client = OpenPhoto()
+    resp = client.get("/photos/list.json")
+    resp = client.post("/photo/62/update.json", tags=["tag1", "tag2"])
+
+<a name="python_classes"></a>
+#### Python classes/methods
+
+    from openphoto import OpenPhoto
+    client = OpenPhoto()
+    photos = client.photos.list()
+    photos[0].update(tags=["tag1", "tag2"])
+    print photos[0].tags
+
+The OpenPhoto Python class hierarchy mirrors the [OpenPhoto API](http://theopenphotoproject.org/documentation) endpoint layout. For example, the calls in the example above use the following API endpoints:
+
+* ``client.photos.list() -> /photos/list.json``
+* ``photos[0].update()   -> /photo/<id>/update.json``
+
+<a name="api_versioning"></a>
+### API Versioning
+
+It may be useful to lock your application to a particular version of the OpenPhoto API.
+This ensures that future API updates won't cause unexpected breakages.
+
+To do this, add the optional ```api_version``` parameter when creating the client object:
+
+    from openphoto import OpenPhoto
+    client = OpenPhoto(api_version=2)
+
+----------------------------------------
+
+<a name="cli"></a>
+### Using from the command line
+
+You can run commands to the OpenPhoto API from your shell!
+
+These are the options you can pass to the shell program:
+
+    --help         # Display help text
+    -c config_file # Either the name of a config file in ~/.config/openphoto/ or a full path to a config file
+    -h hostname    # Overrides config_file for unauthenticated API calls
+    -e endpoint    # [default=/photos/list.json]
+    -X method      # [default=GET]
+    -F params      # e.g. -F 'title=my title' -F 'tags=mytag1,mytag2'
+    -p             # Pretty print the json
+    -v             # Verbose output
+
+<a name="cli-examples"></a>
+#### Command line examples
+
+    # Upload a public photo to the host specified in ~/.config/openphoto/default
+    openphoto -p -X POST -e /photo/upload.json -F 'photo=@/path/to/photo/jpg' -F 'permission=1'
+    {
+        "code":201,
+        "message":"Photo 1eo uploaded successfully",
+        "result":{
+            "actor":"[email protected]",
+            "albums":[],
+            ...
+            ...
+        }
+    }
+
+    # Get a thumbnail URL from current.openphoto.me (unauthenticated access)
+    openphoto -h current.openphoto.me -p -e /photo/62/view.json -F 'returnSizes=20x20'
+    {
+        "code":200,
+        "message":"Photo 62",
+        "result":{
+            "actor":"",
+            "albums":[
+                "1"
+            ],
+            ...
+            ...
+            "path20x20":"http://current.openphoto.me/photo/62/create/36c0a/20x20.jpg",
+            "pathBase":"http://awesomeness.openphoto.me/base/201203/7ae997-Boracay-Philippines-007.jpg",
+            "permission":"1",
+            "photo20x20":[
+                "http://current.openphoto.me/photo/62/create/36c0a/20x20.jpg",
+                13,
+                20
+            ],
+            ...
+            ...
+        }
+    }    
diff --git a/docs/libraries/readme.markdown b/docs/libraries/readme.markdown
@@ -0,0 +1,12 @@
+If you're looking for our language libraries, you're in the right place. The documentation for our various language libraries lives here. 
+
+Currently we have libraries for:
+
+* PHP
+* Python
+* Javascript
+* Java
+* Objective-C
+* Ruby
+
+Is your favorite language not listed? Contact us or better yet, write your own.
diff --git a/docs/plugins/readme.markdown b/docs/plugins/readme.markdown
@@ -0,0 +1,3 @@
+If you're looking for documentation on Trovebox's various plugins, you're in the right place. 
+
+Questions? Want to write your own plugin? Email our mailing list at [email protected].