From 489cf15bcea508cd8dc7518c7cd39fb9bdab4b97 Mon Sep 17 00:00:00 2001 From: Jeremy Prevost Date: Fri, 4 Mar 2016 15:28:06 -0500 Subject: [PATCH] Initial docs --- .gitignore | 3 +++ Gemfile | 1 + Gemfile.lock | 2 ++ README.md | 47 ++++++++++++++++++++++++++++++++++------ app/models/epdcx.rb | 15 +++++++++++++ app/models/mets.rb | 11 ++++++++++ app/models/submission.rb | 15 +++++++++++++ 7 files changed, 87 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index df0815a..abda066 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,6 @@ coverage public/uploads/* *.pid + +*.yardoc/ +doc/* diff --git a/Gemfile b/Gemfile index 053a444..937e71c 100644 --- a/Gemfile +++ b/Gemfile @@ -40,6 +40,7 @@ group :development do gem 'annotate' gem 'rubocop' gem 'web-console' + gem 'yard' end group :test do diff --git a/Gemfile.lock b/Gemfile.lock index 84f1520..a1daee4 100644 --- a/Gemfile.lock +++ b/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 diff --git a/README.md b/README.md index 0530e4e..7013936 100644 --- a/README.md +++ b/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. diff --git a/app/models/epdcx.rb b/app/models/epdcx.rb index 3cdf64e..ae4aae3 100644 --- a/app/models/epdcx.rb +++ b/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 diff --git a/app/models/mets.rb b/app/models/mets.rb index ea2f265..2a1bd8a 100644 --- a/app/models/mets.rb +++ b/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 diff --git a/app/models/submission.rb b/app/models/submission.rb index a395260..6147e23 100644 --- a/app/models/submission.rb +++ b/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