From 0f7fe6a46e596be97b13391de27a151ee264eb9c Mon Sep 17 00:00:00 2001 From: Tom Elliott Date: Wed, 29 Jan 2025 08:58:23 +1300 Subject: [PATCH] add some documentation --- .Rbuildignore | 3 ++ .github/workflows/pkgdown.yaml | 49 +++++++++++++++++++++ .gitignore | 2 + DESCRIPTION | 4 ++ Makefile | 3 ++ _pkgdown.yml | 26 +++++++++++ vignettes/.gitignore | 3 ++ vignettes/simple-react-app.Rmd | 79 ++++++++++++++++++++++++++++++++++ 8 files changed, 169 insertions(+) create mode 100644 .github/workflows/pkgdown.yaml create mode 100644 .gitignore create mode 100644 _pkgdown.yml create mode 100644 vignettes/.gitignore create mode 100644 vignettes/simple-react-app.Rmd diff --git a/.Rbuildignore b/.Rbuildignore index 7c6536c..ee98004 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -3,3 +3,6 @@ ^Makefile$ node_modules ^\.github$ +^_pkgdown\.yml$ +^docs$ +^pkgdown$ diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml new file mode 100644 index 0000000..bfc9f4d --- /dev/null +++ b/.github/workflows/pkgdown.yaml @@ -0,0 +1,49 @@ +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples +# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help +on: + push: + branches: [main, master] + pull_request: + release: + types: [published] + workflow_dispatch: + +name: pkgdown.yaml + +permissions: read-all + +jobs: + pkgdown: + runs-on: ubuntu-latest + # Only restrict concurrency for non-PR jobs + concurrency: + group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + + - uses: r-lib/actions/setup-pandoc@v2 + + - uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + extra-packages: any::pkgdown, local::. + needs: website + + - name: Build site + run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) + shell: Rscript {0} + + - name: Deploy to GitHub pages 🚀 + if: github.event_name != 'pull_request' + uses: JamesIves/github-pages-deploy-action@v4.5.0 + with: + clean: false + branch: gh-pages + folder: docs diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..31d5365 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +inst/doc +docs diff --git a/DESCRIPTION b/DESCRIPTION index 828b6e7..9ebd458 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -15,4 +15,8 @@ Imports: rlang, Rserve Suggests: + knitr, + rmarkdown, testthat (>= 3.0.0) +VignetteBuilder: knitr +URL: http://tomelliott.co.nz/ts/ diff --git a/Makefile b/Makefile index ff55248..fb905d7 100644 --- a/Makefile +++ b/Makefile @@ -17,3 +17,6 @@ README.md: README.Rmd install test: Rscript -e "devtools::test()" + +site: install + Rscript -e "pkgdown::build_site()" diff --git a/_pkgdown.yml b/_pkgdown.yml new file mode 100644 index 0000000..abccc4c --- /dev/null +++ b/_pkgdown.yml @@ -0,0 +1,26 @@ +url: http://tomelliott.co.nz/ts/ +template: + bootstrap: 5 + bootswatch: cosmo + +reference: + - title: Building apps + desc: Writing and compiling functions into Rserve apps. + - contents: + - ts_function + - ts_app + - ts_compile + - ts_deploy + - title: Types + desc: Type helper functions for defining argument and return types. + - contents: + - ts_logical + - ts_integer + - ts_numeric + - ts_character + - ts_factor + - ts_list + - ts_dataframe + - ts_null + - ts_void + - ts_object diff --git a/vignettes/.gitignore b/vignettes/.gitignore new file mode 100644 index 0000000..c911dc7 --- /dev/null +++ b/vignettes/.gitignore @@ -0,0 +1,3 @@ +*.html +*.R +faithful-demo diff --git a/vignettes/simple-react-app.Rmd b/vignettes/simple-react-app.Rmd new file mode 100644 index 0000000..05103be --- /dev/null +++ b/vignettes/simple-react-app.Rmd @@ -0,0 +1,79 @@ +--- +title: "Build a simple ReactJS app" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{simple-react-app} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +We will create a simple [ReactJS](https://reactjs.org/) application that implements our favourite *Old Faithful* dataset. Of course, this is not a great use-case for Rserve as it would be more appropriate to use a REST API, but it is a simple example to demonstrate how to use Rserve with a front-end application. + +## Install the ts package + +```r +devtools::install_github('tmelliott/ts') +``` + +## Write the R code + +The code is saved in a file called `faithful-app.R`, and we can preview the results by calling the functions: + +```{r setup} +cat(readLines('faithful-app.R'), sep = '\n') + +source('faithful-app.R') + +get_hist$call(10) +``` + +That's it! We'll use `ts_deploy()` later to create the server code and Typescript schema for the app. + +TODO: call ts_compile() from ts_deploy()? + +## Create the React app + +```bash +pnpm create vite faithful-demo --template vanilla-ts +cd faithful-demo +pnpm install +pnpm run dev +``` + +You should now be able to see the default Vite app running at `http://localhost:5173` (or similar, see the console output). + +Now install the `rserve-ts` and `zod` packages: + +```bash +pnpm install rserve-ts zod +``` + +### Create the server code + +We now use the `ts_deploy()` function to create two files: + +- `faithful-app.rserve.R` is the file that will start the Rserve instance with your apps functions available. +- `faithful-app.rserve.ts` contains the TypeScript schema (using [zod](https://zod.dev)) that will let you use the R functions directly in the app like any other typescript function! + +We'll send these straight to the `faithful-demo/src` directory. + +```r +ts_compile('faithful-app.R', file = 'faithful-demo/src/faithful-app.rserve.ts') +ts_deploy('faithful-app.R', file = 'faithful-demo/src/faithful-app.rserve.R') +``` + +### Write the app + +The rest of the process simply requires writing TypeScript code. I won't go into detail since that's not the focus of this vignette, but below you can see the code written with some basic comments. Copy and paste these to get the app running. + +```typescript +// main.ts + +```