Added api documentation

.gitignore

@@ -22,56 +22,12 @@
 __pycache__/
 *.py[cod]
 
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-env/
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-
 # Sphinx documentation
 docs/_build/
 
+# Vagrant
+.vagrant/
+
 # PyBuilder
 target/
 
@@ -85,47 +41,6 @@ target/
 .idea/
 # if you remove the above rule, at least ignore the following:
 
-# User-specific stuff:
-# .idea/workspace.xml
-# .idea/tasks.xml
-# .idea/dictionaries
-
-# Sensitive or high-churn files:
-# .idea/dataSources.ids
-# .idea/dataSources.xml
-# .idea/sqlDataSources.xml
-# .idea/dynamic.xml
-# .idea/uiDesigner.xml
-
-# Gradle:
-# .idea/gradle.xml
-# .idea/libraries
-
-# Mongo Explorer plugin:
-# .idea/mongoSettings.xml
-
-## File-based project format:
-*.ipr
-*.iws
-
-## Plugin-specific files:
-
-# IntelliJ
-out/
-
-# mpeltonen/sbt-idea plugin
-.idea_modules/
-
-# JIRA plugin
-atlassian-ide-plugin.xml
-
-# Crashlytics plugin (for Android Studio and IntelliJ)
-com_crashlytics_export_strings.xml
-crashlytics.properties
-crashlytics-build.properties
-
-
-
 ### Eclipse template
 *.pydevproject
 .metadata
@@ -143,27 +58,5 @@ local.properties
 # Eclipse Core
 .project
 
-# External tool builders
-.externalToolBuilders/
-
-# Locally stored "Eclipse launch configurations"
-*.launch
-
-# CDT-specific
-.cproject
-
-# JDT-specific (Eclipse Java Development Tools)
-.classpath
-
-# PDT-specific
-.buildpath
-
-# sbteclipse plugin
-.target
-
-# TeXlipse plugin
-.texlipse
-
-
 
 build

README.md

@@ -14,8 +14,31 @@ In the meantime, please continue to use the existing documentation that can be
 found on our [website](http://incubator.apache.org/wave), in the [wiki](https://cwiki.apache.org/confluence/display/WAVE/Home),
 and at [Wave Protocol (old website)](http://www.waveprotocol.org).
 
-Building the Documentation
---------------------------
+Building the Documentation - (Vagrant) - Recommended
+----------------------------------------------------
+
+To simplify setup a vagrant file has been included to install a small ubuntu vm which can be ssh'ed into.
+
+ Requirements: 
+
+  * Vagrant installed
+  * Virtual Box installed
+  * internet connection
+
+If you are new to how vagrant works the following commands will let you be able to use the system. These commands should
+be run inside a terminal/console after Vagrant and virtual box are installed.
+
+`vagrant up` will download and install a linux OS into a vm hosted on your machine, this will also install all the 
+    requirements for building the project.
+
+`vagrant ssh` will allow you to ssh into the vm and cd'ing into `/vagrant` will allow you to run the make commands 
+    (see commands section below).
+
+`vagrant help` allows you to view all other vagrant commands including shutting down the vm and deleting it.
+
+
+Building the Documentation - (Manually)
+---------------------------------------
 
 You will need Python and Sphinx installed for HTML documentation.
 If you would also like the PDF formats, you will need a LaTeX distribution installed as well.
@@ -25,5 +48,8 @@ On a Debian-based distribution, you can probably just run:
 apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
 ```
 
+Make Commands
+-------------
+
 To build the actual documentation, you should run `make doc-html` or `make doc-pdf`, depending on which type you want.
 To see all commands, please run `make help`.

Vagrantfile

@@ -0,0 +1,33 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# All Vagrant configuration is done below. The "2" in Vagrant.configure
+# configures the configuration version (we support older styles for
+# backwards compatibility). Please don't change it unless you know what
+# you're doing.
+Vagrant.configure(2) do |config|
+  config.vm.box = "ubuntu/trusty64"
+  config.vm.provision :shell, path: "scripts/vagrant/dev.sh"
+  config.vm.post_up_message = "Apache Wave Docs setup is complete see readme for more info."
+
+  config.vm.provider "virtualbox" do |v|
+    v.name = "Apache Wave Docs dev"
+  end
+end

scripts/vagrant/dev.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+apt-get update
+apt-get install -y build-essential python-sphinx texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
+
+# theme specific install (read the docs theme)
+apt-get install -y python-pip
+pip install sphinx_rtd_theme

source/api/data/attachments.rst

@@ -0,0 +1,146 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+..   http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+Attachments
+===========
+
+An attachment is a type of element. Just like other elements, it can be
+created, updated, and deleted from a blip. For more information on doing
+operations on a blip, please refer to Blip Operations.
+
+.. toctree::
+
+Reading Attachements
+--------------------
+
+You can read wave attachment content and attributes by using the getters of
+the attributes of an attachment: Attachment Id, Attachment URL, Caption, Data,
+and MIME Type.
+
+The following table provides detailed descriptions on these attributes:
+
+Attribute Name	Description
+Attachment Id	Unique ID Assigned to an Attachment
+Attachment URL	URL to Use to Download the Attachment
+Caption	        Caption or File Name for the Attachment
+Data	        Raw Binary Data for the Attachment
+MIME Type	    Attachment MIME Type (If Can be Determined)
+
+The following is a java example of getting a list of urls for all attachments
+in the blip. The code first iterates over all of the elements in a blip. If an
+element is an attachment, it gets the attachment URL, and puts it into a list:
+
+* `blip.getElements().values()` returns all of the elements in a blip.
+* `element.isAttachment()` returns true if the element is an attachment.
+* `((Attachment)element).getAttachmentUrl()` returns the attachment URL.
+
+.. code-block:: java
+
+    private List<String> getAllAttachmentUrls(Blip blip) {
+      List<String> urls = new ArrayList<String>();
+      Collection<Element> elements = blip.getElements().values();
+      for (Element element : elements) {
+        if (element.isAttachment()) {
+          urls.add(((Attachment) element).getAttachmentUrl());
+        }
+      }
+      return urls;
+    }
+
+The following is a Python example of getting an attachment URL. If the blip has
+an attachment, the code appends the first attachment URL to the blip.
+
+.. code-block:: python
+
+    def OnBlipSubmitted(event, wavelet):
+      blip = event.blip
+      attachment = blip.first(element.Attachment)
+      if attachment:
+        blip.append("Attachment URL is:" + attachment.value().get("attachmentUrl"))
+
+Writing Attachments
+-------------------
+
+Attachments can be created, updated, and deleted. You create an attachment by
+providing an attachment caption and data. You update an attachment by replacing
+the old attachment with a new attachment. You delete an attachment by removing
+the attachment element.
+
+The following is a java example of creating an attachment in wave. The code
+iterates over the blips in a wavelet, gets the text content, creates an
+attachment with the concatenated content as data, and inserts the attachment in
+a new blip:
+
+`wavelet.getBlips().values()` returns all of the blips in a wavelet.
+`blip.all().values()` returns the blip contents
+`new Attachment("export.txt", exportedWave.toString().getBytes())`
+returns a new attachment.
+
+.. code-block:: java
+
+    private void exportText(Wavelet wavelet) {
+      StringBuilder exportedWave = new StringBuilder();
+
+      for (Blip blip : wavelet.getBlips().values()) {
+        exportedWave.append(blip.getContent());
+      }
+      Attachment attachment = new Attachment("export.txt",
+          exportedWave.toString().getBytes());
+      wavelet.reply("\n").append(attachment);
+    }
+
+The following is a python example of creating an attachment in wave. The code
+fetches an URL content, and creates an attachment with the content.
+
+.. code-block:: python
+
+    def OnBlipSubmitted(event, wavelet):
+      blip = event.blip
+      fileData=urllib2.urlopen("http://www.google.com/logos/poppy09.gif").read()
+      attachment = element.Attachment(caption="new file", data=fileData)
+      blip.append(attachment)
+
+The following is a java example of importing an attachment into wave by
+replacing it with its content. This example assumes that the attachment in the
+blip is text attachment. The code finds the first attachment in the blip, and
+replaces it with the attachment content:
+
+* `blip.first(ElementType.ATTACHMENT)` returns a blip content reference of the
+  first attachment.
+* `(Attachment) attachmentRef.value()` returns an attachment element.
+* `attachmentRef.replace(new String(attachment.getData()))` replaces an
+  attachment with its content.
+
+.. code-block:: java
+
+    private void replaceAttachment(Blip blip) {
+      BlipContentRefs attachmentRef = blip.first(ElementType.ATTACHMENT);
+      if(attachmentRef != null) {
+        Attachment attachment = (Attachment) attachmentRef.value();
+        attachmentRef.replace(new String(attachment.getData()));
+      }
+    }
+
+With the ability of reading and writing attachment in wave, you can do a lot of
+things. Below are a few more ideas in addition to import and export:
+
+* Origami Photo Album: you can read a list of images, compose the images with a
+  few styles, and attach the images back to wave.
+* Chart Creation: you can read a file, transform the content of the file to a
+  chart, and insert the chart into wave.
+* File concatination: you can read all the files from a wavelet, concatinate
+  the contents, create a new file, and insert into wave.