Initial docs

.gitignore

@@ -25,3 +25,6 @@ coverage
 public/uploads/*
 
 *.pid
+
+*.yardoc/
+doc/*

Gemfile

@@ -40,6 +40,7 @@ group :development do
   gem 'annotate'
   gem 'rubocop'
   gem 'web-console'
+  gem 'yard'
 end
 
 group :test do

Gemfile.lock

@@ -287,6 +287,7 @@ GEM
     websocket-extensions (0.1.2)
     xpath (2.0.0)
       nokogiri (~> 1.3)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
@@ -328,6 +329,7 @@ DEPENDENCIES
   vcr
   web-console
   webmock
+  yard
 
 BUNDLED WITH
    1.11.2

README.md

@@ -4,16 +4,37 @@
 [![Dependency Status](https://gemnasium.com/MITLibraries/QuickSubmit.svg)](https://gemnasium.com/MITLibraries/QuickSubmit)
 [![Code Climate](https://codeclimate.com/github/MITLibraries/QuickSubmit/badges/gpa.svg)](https://codeclimate.com/github/MITLibraries/QuickSubmit)
 [![Coverage Status](https://coveralls.io/repos/github/MITLibraries/QuickSubmit/badge.svg?branch=master)](https://coveralls.io/github/MITLibraries/QuickSubmit?branch=master)
+[![Documentation](https://img.shields.io/badge/documentation--blue.svg)](http://www.rubydoc.info/github/MITLibraries/QuickSubmit)
 
 ## What is this?
 
-QuickSubmit will be a brief form where users can upload an article along with sparse metadata. This will be transformed into METS and then SWORD and submitted to an Institutional Repository (DSpace for now).
+QuickSubmit will be a brief form where users can upload an article along with
+sparse metadata. This will be transformed into METS and then SWORD and
+submitted to an Institutional Repository (tested only with DSpace for now).
+
+A `callback_uri` is included in the METS, and the IR should post back JSON to
+include the status of `approved` along with a handle when the submission is
+approved into the repository. If Submissions are automatically approved and
+the handle is returned during the Sword deposit, this is unnecessary to
+configure at the repository level.
+
+The `callback_uri` contains a UUID for the Submission in QuickSubmit as part
+of the URI so there is no need to include that in the JSON.
+
+Example JSON:
+```json
+{
+  "status": "approved",
+  "handle": "http://handle.net/123456/789"
+}
+```
+
 
 ## Testing with FakeS3
 
 To prevent using a real S3 service in testing (and development if
 you prefer), you can use the provided rake tasks `rake fakes3:start`
-and `rake fakes3:stop` to spin up a fake of the service. 
+and `rake fakes3:stop` to spin up a fake of the service.
 
 ## Required Environment Variables
 
@@ -25,12 +46,24 @@ and `rake fakes3:stop` to spin up a fake of the service.
 
 `SWORD_ENDPOINT`: URI of the sword service to deposit packages to
 
-`SWORD_USERNAME`: username for sword service
+`SWORD_USERNAME`: username for sword endpoint
+
+`SWORD_PASSWORD`: password for the sword endpoint
+
+`S3_BUCKET`: whatever your bucket is. With fakes3 (for dev/test) using `fakebucket` as a value is best.
+
+`AWS_ACCESS_KEY_ID`: your Amazon S3 bucket access key id. (not required with fakes3)
 
-`SWORD_PASSWORD`: password for the sword service
+`AWS_SECRET_ACCESS_KEY` your Amazon S3 bucket secret access key. (not required with fakes3)
 
-`S3_BUCKET`
+## Optional Environment Variables
 
-`AWS_ACCESS_KEY_ID`
+`DISABLE_ALL_EMAIL`: set to `true` to not send any emails at all. This
+disables critical communication portions of the app and should not be used
+in production. This option is likely to be removed in the future.
 
-`AWS_SECRET_ACCESS_KEY`
+`FAKE_AUTH_ENABLED`: set to `true` to use `:devloper` mode Omniauth which
+prompts for and accepts any name/email combination. This is useful in PR
+testing to avoid needing to configure the OpenID provider with a fleeting
+hostname of the PR site. It can also be use in development, but never in
+production.

app/models/epdcx.rb

@@ -1,4 +1,18 @@
+# An EPDCX XML document for a Submission
 class Epdcx
+  # Creates an EPDCX XML document for a Submission
+  #
+  # @note This is called from within a {Mets} document
+  # @param xml
+  #   Existing Nokogiri XML document to embed EPDCX into. In the context
+  #   of this application, it will be a {Mets} document
+  # @param submission [Submission]
+  # @param callback_uri
+  #   Text based representation of a URI the will be included
+  #   in the mets.xml document that a remote server can use to communicate back
+  #   with a status update for the Submission
+  # @see Mets
+  # @see Submission
   def initialize(xml, submission, callback_uri)
     @xml = xml
     @callback_uri = callback_uri
@@ -9,6 +23,7 @@ def initialize(xml, submission, callback_uri)
     end
   end
 
+  # Converts the built Nokogiri Document into standard xml
   def to_xml
     @xml.to_xml
   end

app/models/mets.rb

@@ -1,10 +1,21 @@
+# A METS XML document for a Submission
 class Mets
+  # Creates a METS XML document for a Submission
+  #
+  # @param submission [Submission]
+  # @param callback_uri
+  #   Text based representation of a URI the will be included
+  #   in the mets.xml document that a remote server can use to communicate back
+  #   with a status update for the Submission
+  # @see Submission
+  # @see Epdcx
   def initialize(submission, callback_uri)
     @submission = submission
     @callback_uri = callback_uri
     @builder = xml_builder
   end
 
+  # Converts the built Nokogiri Document into standard xml
   def to_xml
     @builder.to_xml
   end

app/models/submission.rb

@@ -18,6 +18,7 @@
 #  funders           :string
 #
 
+# A {User} supplied set of metadata with attached documents
 class Submission < ActiveRecord::Base
   belongs_to :user
   validates :user, presence: true
@@ -32,6 +33,7 @@ class Submission < ActiveRecord::Base
   serialize :funders, JSON
   before_create :generate_uuid
 
+  # Ensures submitted funders are allowed
   def funders_are_valid
     return unless funders.present?
     funders.each do |funder|
@@ -40,10 +42,12 @@ def funders_are_valid
     end
   end
 
+  # Convience method to check if the Submission status is 'approved'
   def status_approved?
     status == 'approved'
   end
 
+  # Generate a {Mets} XML representation of the Submission
   def to_mets(callback)
     Mets.new(self, callback).to_xml
   end
@@ -79,6 +83,11 @@ def to_sword_package(callback)
     end
   end
 
+  # Returns a usable URI associated S3 documents
+  # @param document
+  #   A reference to an S3 document from Submission.documents
+  # @return a usable URI based on whether or not fakes3 or real
+  #   S3 is being used.
   def document_uri(document)
     if document.include?('localhost')
       swap = "localhost:10001/#{ENV['S3_BUCKET']}/"
@@ -88,14 +97,19 @@ def document_uri(document)
     end
   end
 
+  # An array of funders that does not include UI only funders
   def funders_minus_ui_only_funders
     funders - ui_only_funders
   end
 
+  # This includes both funders we want to include in METS and
+  # funders that we only want to display in the UI
+  # @note this array is used to both generate the UI and validate the input
   def valid_funders
     submittable_funders + ui_only_funders
   end
 
+  # Funders we want to display in the UI and also include in {Mets}
   def submittable_funders
     ['Department of Defense (DoD)',
      'Department of Energy (DOE)',
@@ -108,6 +122,7 @@ def submittable_funders
      'United States Department of Agriculture (USDA)']
   end
 
+  # Funders we want to display in the UI, but not include in {Mets}
   def ui_only_funders
     ['None / Other']
   end