README.md in doc_raptor-0.2.2 vs README.md in doc_raptor-0.2.3
- old
+ new
@@ -1,95 +1,175 @@
-DocRaptor
-==========
+# DocRaptor
-This is a Ruby gem providing a simple wrapper around the DocRaptor API. DocRaptor is a web service that allows you to convert [html to pdf](http://docraptor.com) or html to xls.
+This is a Ruby gem providing a simple wrapper around the DocRaptor API. DocRaptor is a web service that allows you to convert [html to pdf](http://docraptor.com) or [html to xls](http://docraptor.com).
-## Usage ######################################################################
+## Usage
-The gem will look for your api key in the ENV variable "DOCRAPTOR_API_KEY". If it is
+The gem will look for your api key in the `ENV` variable `DOCRAPTOR_API_KEY`. If it is
not there, you can set it directly by calling:
-```ruby
+```
DocRaptor.api_key "My API Key Here"
```
Once an API key is set, you can create a PDF document by calling:
-```ruby
+```
DocRaptor.create(:document_content => content)
```
You might want to set other options in that hash:
* `:document_content` - a string containing the content for creating the document
* `:document_url` - a url to visit to get the content for creating the document
* `:document_type` - "pdf" or "xls"; controls the type of document generated; default is "pdf"
* `:name` - an identifier you can use for the document; shows up in doc logs; default is "default"
* `:test` - test mode flag; set to true to while doing testing so the docs won't count against your monthly count; default is false
+* `:prince_options` - see [http://docraptor.com/documentation#pdf_options](http://docraptor.com/documentation#pdf_options) (PDFs only)
* `:async` - create the document asynchonously; default is false
* `:callback_url` - a url that we will hit with a status once the asynchronous document has been fully processed
-* `:prince_options` - see http://docraptor.com/documentation#pdf_options (PDFs only)
The only required parameter is one of `:document_content` or `:document_url`.
-`create` will return an HTTParty response object, the body of which will be the new file (or errors, if the request was not valid).
+`create` will return an [HTTParty](https://github.com/jnunemaker/httparty) response object, the body of which will be the new file (or errors, if the request was not valid).
`create!` will raise an exception instead of return errors if there is a failure of any sort in the document generation process. It otherwise works in the same way as `create`.
If the document is processed asynchronously, a status id will be returned as opposed to the contents of the document. You can then use <METHOD NAME> to get the status of the document. You can pass in a URL to `:callback_url` to be called once an asynchronous job is complete. It will be passed a value of `download_url` which will contain a URL that when visited will provide you with your document. This option does nothing if `:async` is not true.
The `create` call can also take a block, like so:
-```ruby
+```
DocRaptor.create(:document_content => content) do |file, response|
#file is a tempfile holding the response body
#reponse is the HTTParty response object
-end
+end
```
+### Async Doc Creation
To get the status of an async request, you can call:
-```ruby
+```
# uses the id of the most recently created async job
DocRaptor.status
+```
+```
# query some other async job and make it the "active" async job for the DocRaptor class
DocRaptor.status(status_id)
```
`status_id` is the value returned from `DocRaptor.create` when `:async` is true. If you have
-just created a document, status_id defaults to the last status_id received from DocRaptor.
-This will return a hash containing, at the very least, a key of "status" with a value of
-one of the following: { "completed", "failed", "killed", "queued", "working" }. If the
-status is "queued", no other information will be available. If the status is "working",
-there will be a human readable message contained in "message" that gives further details
-as to the state of the document. If the status is "complete" there will be a key of
-"download_url" that will contain a 2 time use URL that, when visited, will provide your
-document. There will also be a key of "download_key" that can be given to the
-DocRaptor.download function to obtain your document. If the status is "killed", it means
-the system had to abort your document generation process for an unknown reason, most
-likely it was taking too long to generate. If the status is "failed" you can check the
-"messages" value for a message and the "validation_errors" value for a more detailed reason
-for the failure to generate your document.
+just created a document, `status_id` defaults to the last `status_id` received from DocRaptor.
+This will return a hash containing, at the very least, a key of `status` with a value of
+one of the following: `{"completed", "failed", "killed", "queued", "working"}`.
-To download an async document, you can visit the URL (download_url) provided via the status
+* If the status is `queued`, no other information will be available.
+* If the status is `working`, there will be a human readable message contained in "message" that gives further details as to the state of the document.
+* If the status is `complete` there will be a key of "download_url" that will contain a 2 time use URL that, when visited, will provide your document.
+
+There will also be a key of `download_key` that can be given to the `DocRaptor.download` function to obtain your document. If the status is `killed`, it means the system had to abort your document generation process for an unknown reason, most likely it was taking too long to generate. If the status is `failed` you can check the `messages` value for a message and the `validation_errors` value for a more detailed reason for the failure to generate your document.
+
+To download an async document, you can visit the URL (`download_url`) provided via the `status`
function or you can call:
-```ruby
+```
# uses the key of the most recently checked async job which is complete
DocRaptor.download
+```
+```
# use some other complete doc's download key
DocRaptor.download(download_key)
```
-`download_key` is the value from the status hash of a call to DocRaptor.status of a completed job. If you have just checked the status of a document and it is completed, `download_key` defaults to that of the document you just checked. The download function works like DocRaptor.create in that you get back either an HTTParty response object or you can give it a block.
+`download_key` is the value from the status hash of a call to `DocRaptor.status` of a completed job.
-## Examples ###################################################################
+* If you have just checked the status of a document and it is completed, `download_key` defaults to that of the document you just checked.
+
+The `download` function works like `DocRaptor.create` in that you get back either an HTTParty response object or you can give it a block.
+
+## Examples
+
Check the examples directory for some simple examples. To make them work, you will need to have the docraptor gem installed (via bundler or gem install).
-For more examples including a full rails example, check https://github.com/expectedbehavior/doc_raptor_examples.
+For more examples including a full rails example, check [https://github.com/expectedbehavior/doc_raptor_examples](https://github.com/expectedbehavior/doc_raptor_examples).
-## Meta #######################################################################
+## Meta
-Maintained by Expected Behavior
+Maintained by [Expected Behavior](http://expectedbehavior.com)
-Released under the MIT license. http://github.com/expected-behavior/docraptor-gem
+Released under the MIT license. [http://github.com/expected-behavior/docraptor-gem](http://github.com/expected-behavior/docraptor-gem)
+
+## Obligatory Raptor
+
+ ''
+ -'
+ .-
+ .:'
+ :-
+ -s-
+ 'sy.
+ .so'
+ -/-
+ '::.
+ .+o'
+ '+hs
+ .yh+
+ :ys-
+ :+/'
+ '/+:
+ :sy:
+ 'shh.
+ -yyo
+ -//-
+ ':/:'
+ :+o/
+ 'syy:
+ ' :yyy.
+ '':+- '/oo+
+ '..-++o++//-' .///.
+ ./++oooooooso+oo+. '/++/'
+ -oosssoosydddhhsosy+- :yyh+
+ .sssyssshddyhddhhhsyso' -yhhh-
+ -syyyyddmmmhyddhyhysyy/ '+shho'
+ -syyydmmmddmddhhyyyysyhy- '-//+o-
+ ./yyhhmmddddhhhyysssyyyydhy. '/ooo+:
+ :syyydmhdddddhyyyssyyyyhhhhho .+hddhs.
+ '/ossyhhhhhddhhhhhhdhhyhhhhhhhh: ''....'' .+shddd/
+ :syosyhhhyyyyhdmddhyyyyyyyhhdhhh-''.-:/++++oooo+/:. ':+ooooso'
+ .+ysoosyyyyyydNmmdyyyyyoosyhdddddho//+osooooosyhyooyoooyhhys+.
+ -oo+++sssyyhmNmmdyyyo-'-/osyhhdddddhssssyyyssyyhhhsyhhysshhy:
+ ':+++oossyhdNNmmhyy+. -/+osyhhddddddhhhhhyyyhdddhhdmhhyyho'
+ '''.:yydNmmdhyy+. ./+syyhhddddmddhdhhyyhdmmdddmmhhys.
+ /yydmmhyys: .:+osyhdddddddddhhhhdmmddhyyddyy+
+ '+syhyssyo. .+/+oshhdddddddhhhhhdNmhyysoohyyo'
+ '/+sooss/' /oo+ooshddddhhhhyhhdmmhysyhdsshyo-
+ -/o++:' /++osssyhhhhyyyyyyhdddhhhhmNyohys:
+ ' :o+++osssyyyyyyssyyhdmmddmmmmhohhs+
+ .oo++oosssyyyysyssyhmNNmmmmdhyooddyo'
+ :/+ssysssyyysyyyyyhdmNNNmyyhyooshhys'
+ ':/sddddhysyssyyyyhhhdmNNysosoooshhyy'
+ ./oyddmmmmmhhyyyyssoosyhdy+ososyshhh+
+ -+yhdddmNmNNmNNmmo/+oyyhhs+osshyshhh/
+ :+hdhhddmmmmmmmNd' '-syhyoshhhsyyyyo'
+ .:odmddddmNmmdddmm+ ./ssoshdhsyysss/
+ ./ohmmmy:smmddhhdmh' ''-oshhysssyys'
+ ./+hdmNd-:mmddhhddo .osydhhyyhho'
+ ./+ydmNMmydmmdddhh: .ssyhddyyhh/
+ odsydmNMNydmmddhh- .ossyhdhyyy.
+ ./'-sdmNN+/dmmddd: +hyssysyyh-
+ 'oyh/.'odddmm/ ohysoossyho'
+ ':hd:'/hhhdmo '.-/+ooosys'
+ '-+osyhhdmy' '/+osy/
+ .syyhhh. '/+osy.
+ 'osssys' -+ooss.
+ '/ooos+' '/oosss.
+ :oo+o+' -shhhyyy/
+ '+ss+oy. .yNmmmdhys.
+ smNdshd: -ydmdhyys/'
+ .mNNdydms :yhyyhy++/.
+ '+ddyyhdy: -sddddo++s+'
+ '.-/ohdmNdyyy' 'odmyss+odd/
+ -+oyhhhhdmmmmdhy+ ':- '.:.
+ 'sMmoosshmmNdmmh/.
+ -oo+---/ddmMhho'
+ :++:-'