Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

update readme to be a little easier to understand

  • Loading branch information...
commit c6cfdc7c932327e32defc1903bc8800fe00577fa 1 parent 7bb2813
@janxious janxious authored
Showing with 39 additions and 34 deletions.
  1. +39 −34 README.md
View
73 README.md
@@ -1,21 +1,20 @@
-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)
```
@@ -26,13 +25,13 @@ You might want to set other options in that hash:
* `: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`.
@@ -40,56 +39,62 @@ If the document is processed asynchronously, a status id will be returned as opp
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.
-
-To download an async document, you can visit the URL (download_url) provided via the status
+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.
+
+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.
+
+* 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
-## 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)
Please sign in to comment.
Something went wrong with that request. Please try again.