[skip vbump] add a vignette (#29)

close #28 
add an introductory vignette

---------

Co-authored-by: 27856297+dependabot-preview[bot]@users.noreply.github.com <27856297+dependabot-preview[bot]@users.noreply.github.com>

DESCRIPTION

@@ -1,11 +1,12 @@
 Type: Package
 Package: sasr
 Title: SAS Interface in R
-Version: 0.1.0
+Version: 0.1.1
 Date: 2023-04-26
 Authors@R: c(
     person("Liming", "Li", , "liming.li@roche.com", role = c("aut", "cre")),
     person("Daniel", "Sabanes Bove", , "daniel.sabanes_bove@roche.com", role = c("aut")),
+    person("Isaac", "Gravestock", , "isaac.gravestock@roche.com", role = c("aut")),
     person("F. Hoffmann-La Roche AG", role = c("cph", "fnd"))
   )
 Description: Provides a SAS interface in R, through 'SASpy'(<https://sassoftware.github.io/saspy/>) and 'reticulate'(<https://rstudio.github.io/reticulate/>).

NEWS.md

@@ -1,4 +1,4 @@
-# sasr 0.1.0
+# sasr 0.1.1
 
 * First CRAN version of the package.
 * The package facilitates the execution of SAS code from R.

README.md

@@ -41,37 +41,6 @@ install_saspy()
 
 After the installation completes, you are ready to use `sasr` package.
 
-## Short Tutorial
-
-To use `sasr`, you need to follow these steps
-
-1. Configure your SAS server in `sascfg_personal.py` under your working directory or the home directory. This is the default file that `sasr` will look at. However, you can still change that through `options(sascfg = )`, then `sasr` will try to find any name that is available in your specified option.
-    1. If you don't know how to create this file, use `sascfg()` to create the file. Required arguments include `host` and `saspath`.
-        1. `sascfg()` only creates ssh based SAS session.
-        1. Only password-less ssh connection is supported, e.g. ssh via public keys.
-        1. `host` is the hostname of the SAS server.
-        1. `saspath` is the SAS executable path on the SAS server.
-        1. Other arguments are added to the configuration file directly.
-        1. `tunnel` and `rtunnel` are required if you want to transfer datasets between R and SAS. Use integers like `tunnel = 9999L` in R, or modify `sascfg_personal.py` to make sure they are integers.
-    1. You can create the configuration by yourself and then SAS connection will not be restricted to ssh.
-    1. You can have multiple configuration files with different file names
-1. Create the SAS session based on the configuration file
-    1. To use the default connection specified in the configuration file, you can run any command like `run_sas`, `df2sd` or `sd2df`.
-        1. The session will be created if there is no session available stored in `.sasr_env$.sas_session`
-        1. If `.sasr_env$.sas_session` is created, this session will be used by default.
-        1. Do not create any variable called `.sas_session` in environment `sasr:::.sasr_env`
-    1. To create the session manually, you can call `sas_session_ssh()`
-        1. `SAS_session` have one argument `sascfg`, pointing to the SAS session configuration file.
-    1. To use multiple sessions, you need to store the session `your_session <- sas_session_ssh(sascfg)`
-1. Transfer the datasets from R to SAS using `df2sd`
-    1. Tunneling must be enabled to transfer datasets.
-    1. The variable names of the datasets should not contain dots otherwise SAS may not recognize.
-    1. The index (row names) will not be transferred to SAS.
-1. Use `run_sas` to submit SAS code to the SAS server.
-    1. The returned value is a named list, `LST` is the result and `LOG` is the log file
-    1. `run_sas` has argument `results=`, it can be either "TEXT" or "HTML". This argument decides the LST format.
-1. Transfer SAS datasets back to R use `sd2df`
-
 ### Short Example
 
 ```{r}

vignettes/introduction.Rmd

@@ -0,0 +1,57 @@
+---
+title: "Introduction to `sasr`"
+package: sasr
+output:
+  rmarkdown::html_document:
+          theme: "spacelab"
+          highlight: "kate"
+          toc: true
+          toc_float: true
+vignette: |
+  %\VignetteIndexEntry{Introduction to `sasr`}
+  %\VignetteEncoding{UTF-8}
+  %\VignetteEngine{knitr::rmarkdown}
+editor_options:
+  chunk_output_type: console
+---
+
+
+## Introduction to `sasr`
+
+`sasr` is a package to provide `SAS` interface in R, with [`saspy`](https://sassoftware.github.io/saspy/) and [`reticulate`](https://rstudio.github.io/reticulate/) as backend.
+
+## Documentations
+
+For functionality wrapped in `sasr`, you can find the documentations through R documentation system, or through online [documentation page](https://insightsengineering.github.io/sasr/latest-tag/).
+However, there can be some other arguments not documented(in `...`), and these arguments are described in `saspy` [documentation page](https://sassoftware.github.io/saspy/).
+
+## Short Tutorial
+
+To use `sasr`, you need to follow these steps
+
+1. Configure your SAS server in `sascfg_personal.py` under your working directory or the home directory. This is the default file that `sasr` will look at. However, you can still change that through `options(sascfg = )`, then `sasr` will try to find any name that is available in your specified option.
+    1. If you don't know how to create this file, use `sascfg()` to create the file. Required arguments include `host` and `saspath`.
+        1. `sascfg()` only creates ssh based SAS session.
+        1. Only password-less ssh connection is supported, e.g. ssh via public keys.
+        1. `host` is the hostname of the SAS server.
+        1. `saspath` is the SAS executable path on the SAS server.
+        1. Other arguments are added to the configuration file directly.
+        1. `tunnel` and `rtunnel` are required if you want to transfer datasets between R and SAS. Use integers like `tunnel = 9999L` in R, or modify `sascfg_personal.py` to make sure they are integers.
+    1. You can create the configuration by yourself and then SAS connection will not be restricted to ssh.
+    1. You can have multiple configuration files with different file names
+1. Create the SAS session based on the configuration file
+    1. To use the default connection specified in the configuration file, you can run any command like `run_sas`, `df2sd` or `sd2df`.
+        1. The session will be created if there is no session available stored in `.sasr_env$.sas_session`
+        1. If `.sasr_env$.sas_session` is created, this session will be used by default.
+        1. Do not create any variable called `.sas_session` in environment `sasr:::.sasr_env`
+    1. To create the session manually, you can call `sas_session_ssh()`
+        1. `SAS_session` have one argument `sascfg`, pointing to the SAS session configuration file.
+    1. To use multiple sessions, you need to store the session `your_session <- sas_session_ssh(sascfg)`
+1. Transfer the datasets from R to SAS using `df2sd`
+    1. Tunneling must be enabled to transfer datasets.
+    1. The variable names of the datasets should not contain dots otherwise SAS may not recognize.
+    1. The index (row names) will not be transferred to SAS.
+1. Use `run_sas` to submit SAS code to the SAS server.
+    1. The returned value is a named list, `LST` is the result and `LOG` is the log file
+    1. `run_sas` has argument `results=`, it can be either "TEXT" or "HTML". This argument decides the LST format.
+1. Transfer SAS datasets back to R use `sd2df`