add vignette

.Rbuildignore

@@ -1,3 +1,5 @@
+^Meta$
+^doc$
 ^misc$
 ^\.vs$
 \.sln$

.gitignore

@@ -1,38 +1,30 @@
+Meta
+doc
 # History files
 .Rhistory
 .Rapp.history
 
 # Session Data files
 .RData
-
 # Example code in package build process
 *-Ex.R
-
 # Output files from R CMD build
 /*.tar.gz
-
 # Output files from R CMD check
 /*.Rcheck/
-
 # RStudio files
 .Rproj.user/
-
 # produced vignettes
 vignettes/*.html
 vignettes/*.pdf
-
 # OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3
 .httr-oauth
-
 # knitr and R markdown default cache directories
 /*_cache/
 /cache/
-
 # Temporary files created by R markdown
 *.utf8.md
 *.knit.md
-
 # Shiny token, see https://shiny.rstudio.com/articles/shinyapps.html
 rsconnect/
-
 misc/

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: AzureCognitive
 Title: Interface to Azure Cognitive Services
-Version: 0.1
+Version: 0.1.0
 Authors@R: c(
     person("Hong", "Ooi", , "hongooi@microsoft.com", role = c("aut", "cre")),
     person("Microsoft", role="cph")
@@ -17,6 +17,8 @@ Imports:
     jsonlite,
     httr (>= 1.3),
 Suggests:
+    knitr,
     testthat
+VignetteBuilder: knitr
 Roxygen: list(markdown=TRUE)
 RoxygenNote: 6.1.1

R/endpoint.R

@@ -183,14 +183,6 @@ cognitive_error_message <- function(cont)
 }
 
 
-# kind - api
-# ComputerVision - vision/v2.0
-# Face - face/v1.0
-# LUIS - luis/v2.0
-# CustomVision.Training - customvision/v3.0
-# CustomVision.Prediction - customvision/v3.0
-# ContentModerator - contentmoderator/moderate/v1.0
-# Text - text/analytics/v2.0
 get_api_path <- function(type)
 {
     switch(type,

README.md

@@ -2,6 +2,8 @@
 
 A package to work with [Azure Cognitive Services](https://azure.microsoft.com/services/cognitive-services/). Both a Resource Manager interface and a client interface to the REST API are provided.
 
+The primary repo for this package is at https://github.com/Azure/AzureCognitive; please submit issues and PRs there. It is also mirrored at the Cloudyr org at https://github.com/cloudyr/AzureCognitive. You can install the development version of the package with `devtools::install_github("Azure/AzureCognitive")`.
+
 ## Resource Manager interface
 
 AzureCognitive extends the class framework provided by [AzureRMR](https://github.com/Azure/AzureRMR) to support Cognitive Services. You can create, retrieve, update, and delete cognitive service resources by calling the corresponding methods for a resource group.

vignettes/intro.Rmd

@@ -0,0 +1,74 @@
+---
+title: "Introduction to AzureCognitive"
+author: Hong Ooi
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Introduction}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{utf8}
+---
+
+AzureCognitive is a package for working with [Azure Cognitive Services](https://azure.microsoft.com/services/cognitive-services/). Both a Resource Manager interface and a client interface to the Cognitive Services REST API are provided. The aim is to provide a foundation that can be built on by other packages that will support specific services (Computer Vision, LUIS, etc).
+
+## Resource Manager interface
+
+AzureCognitive extends the class framework provided by [AzureRMR](https://github.com/Azure/AzureRMR) to support Cognitive Services. You can create, retrieve, update, and delete cognitive service resources by calling the corresponding methods for a resource group.
+
+```r
+az <- AzureRMR::get_azure_login()
+sub <- az$get_subscription("sub_id")
+rg <- sub$get_resource_group("rgname")
+
+# create a new Computer Vision service
+rg$create_cognitive_service("myvisionservice",
+    service_type="ComputerVision", service_tier="S1")
+
+# retrieve it
+cogsvc <- rg$get_cognitive_service("myvisionservice")
+
+# list subscription keys
+cogsvc$list_keys()
+```
+
+## Client interface
+
+AzureCognitive implements basic functionality for communicating with the Cognitive Services REST API. The main functions are `cognitive_endpoint`, which creates an object representing the endpoint, and `call_cognitive_endpoint` to perform the REST calls.
+
+```r
+# getting the endpoint from the resource object
+endp <- cogsvc$get_endpoint()
+
+# or standalone (must provide subscription key or other means of authentication)
+endp <- cognitive_endpoint("https://myvisionservice.cognitiveservices.azure.com/",
+    service_type="ComputerVision", key="key")
+
+# analyze an image
+img_link <- "https://news.microsoft.com/uploads/2014/09/billg1_print.jpg"
+call_cognitive_endpoint(endp,
+    operation="analyze",
+    body=list(url=img_link),
+    options=list(details="celebrities"),
+    http_verb="POST")
+```
+
+The latter call produces output like that below (truncated for brevity).
+
+```
+$categories
+$categories[[1]]
+$categories[[1]]$name
+[1] "people_"
+
+$categories[[1]]$score
+[1] 0.953125
+
+$categories[[1]]$detail
+$categories[[1]]$detail$celebrities
+$categories[[1]]$detail$celebrities[[1]]
+$categories[[1]]$detail$celebrities[[1]]$name
+[1] "Bill Gates"
+
+$categories[[1]]$detail$celebrities[[1]]$confidence
+[1] 0.9999552
+```
+