Docs site (#20)

* Update

* Docs

* Rendering of static widget in pkgdown page

* Update

* Update vignette

* Update

* Update deploy.yml

Author: keller-mark

.github/workflows/deploy.yml

@@ -0,0 +1,87 @@
+name: R
+
+on: [push, pull_request]
+
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  pre_deploy:
+    runs-on: ubuntu-latest
+    env:
+      cache-version: 5
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up libraries for Ubuntu
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libsodium-dev libharfbuzz-dev libfribidi-dev libcurl4-openssl-dev texlive-latex-base texlive-fonts-extra pandoc libmagick++-dev libhdf5-dev
+      - name: Set up R 4.0
+        uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: 4.0
+      - name: Set CRAN mirror
+        run: |
+          cat("\noptions(repos=structure(c(CRAN=\"https://cran.rstudio.com\")))\n", file = "~/.Rprofile", append = TRUE)
+        shell: Rscript {0}
+      - name: Get R and OS version
+        id: get-version
+        run: |
+          cat("::set-output name=os-version::", sessionInfo()$running, "\n", sep = "")
+          cat("::set-output name=r-version::", R.Version()$version.string, "\n", sep = "")
+          cat("::endgroup::\n")
+        shell: Rscript {0}
+      - name: Cache dependencies
+        id: cache-deps
+        uses: actions/cache@v2
+        with:
+          path: ${{ env.R_LIBS_USER }}/*
+          key: ${{ hashFiles('DESCRIPTION') }}-${{ steps.get-version.outputs.os-version }}-${{ steps.get-version.outputs.r-version }}-${{ env.cache-version }}-deps
+      - name: Install dependencies
+        if: steps.cache-deps.outputs.cache-hit != 'true'
+        run: |
+          install.packages(c("devtools", "remotes", "rcmdcheck", "covr"))
+          remotes::install_deps(dependencies = TRUE)
+        shell: Rscript {0}
+        env:
+          GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      - name: rcmdcheck
+        run: |
+          rcmdcheck::rcmdcheck(
+            error_on = "error", # TODO: switch back to "warning"
+            check_dir = "check"
+          )
+        shell: Rscript {0}
+        env:
+          _R_CHECK_FORCE_SUGGESTS_: false
+      - name: Run coverage report
+        run: |
+          covr::package_coverage()
+        shell: Rscript {0}
+      #- name: Downgrade pkgdown
+      #  run: |
+      #    remotes::install_version("pkgdown", "2.0.3")
+      #  shell: Rscript {0}
+      - name: Build docs
+        run: |
+          Rscript -e 'devtools::document(); pkgdown::build_site(new_process = FALSE)'
+          touch docs/.nojekyll
+      - uses: actions/upload-pages-artifact@v1
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          path: ./docs
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: pre_deploy
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        uses: actions/deploy-pages@v1

.gitignore

@@ -1,3 +1,4 @@
 .Rhistory
 .Rproj.user/
-.DS_Store
+.DS_Store
+docs/

DESCRIPTION

@@ -1,18 +1,35 @@
 Package: anyhtmlwidget
 Type: Package
-Title: What the Package Does (Title Case)
+Title: Create interactive widgets using EcmaScript Modules
 Version: 0.1.0
-Author: Who wrote it
-Maintainer: The package maintainer <yourself@somewhere.net>
-Description: More about what it does (maybe more than one line)
-    Use four spaces when indenting paragraphs within the Description.
+Authors@R: c(
+    person(
+      given = "Mark",
+      family = "Keller",
+      email = "mark_keller@g.harvard.edu",
+      role = c("cre", "aut"),
+      comment = c(ORCID = "0000-0003-3003-874X")
+    )
+  )
+Description: Anyhtmlwidget brings concepts from
+    AnyWidget to R.
 License: MIT + file LICENSE
-Encoding: UTF-8
-LazyData: false
+BugReports: https://github.com/keller-mark/anyhtmlwidget/issues
+URL: https://github.com/keller-mark/anyhtmlwidget
+Depends: R (>= 4.0.0)
 Imports:
-  htmlwidgets,
-  R6,
-  shiny,
-  httpuv,
-  jsonlite
+    htmlwidgets,
+    R6,
+    shiny,
+    httpuv,
+    jsonlite
+Encoding: UTF-8
+LazyData: true
+Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.1
+Suggests:
+    testthat,
+    bslib,
+    pkgdown,
+    knitr,
+    rmarkdown

NAMESPACE

@@ -1 +1,5 @@
-exportPattern("^[[:alpha:]]+")
+# Generated by roxygen2: do not edit by hand
+
+export(AnyHtmlWidget)
+export(widgetServer)
+export(widgetUI)

R/widget.R

@@ -35,10 +35,7 @@ the_anyhtmlwidget <- function(esm, values = NULL, ns_id = NULL, width = NULL, he
   )
 }
 
-#' Shiny bindings for anyhtmlwidget
-#'
-#' Output and render functions for using anyhtmlwidget within Shiny
-#' applications and interactive Rmd documents.
+#' Internal Shiny UI binding for anyhtmlwidget.
 #'
 #' @param output_id output variable to read from
 #' @param width,height Must be a valid CSS unit (like \code{'100\%'},
@@ -55,15 +52,21 @@ anyhtmlwidget_output <- function(output_id, width = '100%', height = '400px'){
   htmlwidgets::shinyWidgetOutput(output_id, 'anyhtmlwidget', width, height, package = 'anyhtmlwidget')
 }
 
-#' @name anyhtmlwidget-shiny
-#' @return The Shiny server output.
+#' Internal Shiny server binding for anyhtmlwidget.
 #'
 #' @keywords internal
 render_anyhtmlwidget <- function(expr, env = parent.frame(), quoted = FALSE) {
   if (!quoted) { expr <- substitute(expr) } # force quoted
   htmlwidgets::shinyRenderWidget(expr, anyhtmlwidget_output, env, quoted = TRUE)
 }
 
+#' AnyHtmlWidget
+#' @title AnyHtmlWidget Class
+#' @docType class
+#' @description
+#' Class representing a widget.
+#'
+#' @rdname AnyHtmlWidget
 #' @export
 AnyHtmlWidget <- R6::R6Class("AnyHtmlWidget",
   lock_objects = FALSE,
@@ -81,10 +84,16 @@ AnyHtmlWidget <- R6::R6Class("AnyHtmlWidget",
     .width = NULL,
     .height = NULL
   ),
-  active = list(
-
-  ),
+  active = list(),
   public = list(
+    #' @description
+    #' Create a new widget instance.
+    #' @param .esm The EcmaScript module as a string.
+    #' @param .mode The widget mode.
+    #' @param .width The widget width. Optional.
+    #' @param .height The widget height. Optional.
+    #' @param .commands TODO
+    #' @param ... All other named arguments will be used to create active bindings on the instance.
     initialize = function(.esm, .mode, .width = NA, .height = NA, .commands = NA, ...) {
       private$esm <- .esm
       private$values <- list(...)
@@ -126,56 +135,100 @@ AnyHtmlWidget <- R6::R6Class("AnyHtmlWidget",
       }
       self$`.__enclos_env__`$`.__active__` <- active_env
     },
+    #' @description
+    #' Set a value.
+    #' @param key The key of the value to set.
+    #' @param val The new value.
+    #' @param emit_change Should the on_change handler be called?
     set_value = function(key, val, emit_change = TRUE) {
       private$values[[key]] <- val
       if(emit_change && !is.null(private$change_handler)) {
         # Should this only call the callback if the current value is different than the new value?
         private$change_handler(key, val)
       }
     },
+    #' @description
+    #' Register a change handler to call if emit_change is TRUE in set_value.
+    #' @param callback A callback function to register.
     on_change = function(callback) {
       private$change_handler <- callback
     },
+    #' @description
+    #' Get a particular value.
+    #' @param key The key of the value to get.
+    #' @returns The value.
     get_value = function(key) {
       return(private$values[[key]])
     },
+    #' @description
+    #' Get the ESM string.
+    #' @returns The ESM string.
     get_esm = function() {
       return(private$esm)
     },
+    #' @description
+    #' Get all widget values
+    #' @returns List of values.
     get_values = function() {
       return(private$values)
     },
+    #' @description
+    #' Get the widget width.
+    #' @returns The width.
     get_width = function() {
       return(private$.width)
     },
+    #' @description
+    #' Get the widget height.
+    #' @returns The height.
     get_height = function() {
       return(private$.height)
     },
+    #' @description
+    #' Set all values. TODO: is this ever used?
+    #' @param new_values A list of new values.
     set_values = function(new_values) {
       private$values <- new_values
     },
+    #' @description
+    #' Set the widget mode.
+    #' @param mode The new widget mode.
     set_mode = function(mode) {
       if(!mode %in% c("static", "gadget", "shiny", "dynamic")) {
         stop("Invalid widget mode.")
       }
       private$mode <- mode
     },
+    #' @description
+    #' Start the server, if not running.
     start_server = function() {
       if(is.null(private$server)) {
         private$server <- start_server(self, host = private$server_host, port = private$server_port)
       }
     },
+    #' @description
+    #' Stop the server, if running.
     stop_server = function() {
       if(!is.null(private$server)) {
         private$server$stop()
       }
     },
+    #' @description
+    #' Get the server hostname.
+    #' @return The hostname as a string.
     get_host = function() {
       return(private$server_host)
     },
+    #' @description
+    #' Get the server port.
+    #' @returns The port number.
     get_port = function() {
       return(private$server_port)
     },
+    #' @description
+    #' Custom print function for the R6 class.
+    #' If mode is "shiny", falls back to original R6 print behavior.
+    #' Otherwise, renders the widget.
     print = function() {
       if(private$mode == "shiny") {
         # If Shiny mode, we just want to use the original R6 print behavior.
@@ -186,6 +239,8 @@ AnyHtmlWidget <- R6::R6Class("AnyHtmlWidget",
         self$render()
       }
     },
+    #' @description
+    #' Render the widget.
     render = function() {
       if(private$mode == "static") {
         invoke_static(self)
@@ -200,6 +255,7 @@ AnyHtmlWidget <- R6::R6Class("AnyHtmlWidget",
   )
 )
 
+#' @keywords internal
 invoke_static <- function(w) {
   w <- the_anyhtmlwidget(
     esm = w$get_esm(),
@@ -210,6 +266,7 @@ invoke_static <- function(w) {
   print(w)
 }
 
+#' @keywords internal
 invoke_dynamic <- function(w) {
   w$start_server()
   w <- the_anyhtmlwidget(
@@ -223,6 +280,7 @@ invoke_dynamic <- function(w) {
   print(w)
 }
 
+#' @keywords internal
 invoke_gadget <- function(w) {
   ui <- shiny::tagList(
     anyhtmlwidget_output(output_id = "my_widget", width = '100%', height = '100%')
@@ -261,13 +319,25 @@ invoke_gadget <- function(w) {
   shiny::runGadget(ui, server)
 }
 
-# Shiny module UI
+#' Shiny module UI for anyhtmlwidgets.
+#'
+#' @param id The output ID.
+#' @param width The widget width. Optional.
+#' @param height The widget height. Optional.
+#'
+#' @export
 widgetUI <- function(id, width = '100%', height = '400px') {
   ns <- shiny::NS(id)
   anyhtmlwidget_output(output_id = ns("widget"), width = width, height = height)
 }
 
-# Shiny module server
+#' Shiny module server for anyhtmlwidgets.
+#'
+#' @param id The matching output ID used in the Shiny UI.
+#' @param w The widget instance.
+#' @returns reactiveValues corresponding to the widget's active bindings.
+#'
+#' @export
 widgetServer <- function(id, w) {
   ns <- shiny::NS(id)
   shiny::moduleServer(

README.md

@@ -6,8 +6,6 @@ Bringing core concepts from [anywidget](https://github.com/manzt/anywidget) to R
 - Access state from JS using the same AnyWidget `model` API.
 - Bidirectional communication (R <-> JS)
 
-Note: this is currently an experiment
-
 ## Installation
 
 ```R