From 50e927d0e0ae1a79fc18aa7663fe6ec053000fde Mon Sep 17 00:00:00 2001 From: emse-p4a-gwu Date: Mon, 16 Dec 2024 12:08:50 -0500 Subject: [PATCH] remove child chunks and simplify pkgdown --- README.Rmd | 74 ++++++++++++-- README.md | 2 - man/rmdchunks/concept.Rmd | 19 ---- man/rmdchunks/install_R_Quarto.Rmd | 8 -- man/rmdchunks/install_surveydown.Rmd | 32 ------ man/rmdchunks/motivation.Rmd | 8 -- man/rmdchunks/todo.Rmd | 1 - pkgdown/_pkgdown.yml | 17 ++-- vignettes/surveydown.Rmd | 143 --------------------------- 9 files changed, 74 insertions(+), 230 deletions(-) delete mode 100644 man/rmdchunks/concept.Rmd delete mode 100644 man/rmdchunks/install_R_Quarto.Rmd delete mode 100644 man/rmdchunks/install_surveydown.Rmd delete mode 100644 man/rmdchunks/motivation.Rmd delete mode 100644 man/rmdchunks/todo.Rmd delete mode 100644 vignettes/surveydown.Rmd diff --git a/README.Rmd b/README.Rmd index 91f8ebf..7a5ec67 100644 --- a/README.Rmd +++ b/README.Rmd @@ -27,31 +27,87 @@ status](https://www.r-pkg.org/badges/version/surveydown)](https://CRAN.R-project ## What is surveydown? -```{r child="man/rmdchunks/concept.Rmd"} -``` +**surveydown** is a flexible, open-source platform for making surveys with [R](https://www.r-project.org/), [Quarto](https://quarto.org/), [Shiny](https://shiny.posit.co/), and [Supabase](https://supabase.com/). + +
+image showing the three technologies used in the surveydown platform along with their logos: quarto (for designing surveys), shiny (for rendering the survey), and supabase (for storing data) +
+ +
+ +Here's how it works: + +1. Design your survey as a [Quarto](https://quarto.org/) document using markdown and R code. +2. Render your survey into a [shiny](https://shiny.posit.co/) app that can be hosted online and sent to respondents. +3. Store survey responses in a PostgreSQL database - we recommend [Supabase](https://supabase.com/) as a free, secure, and easy to use option. + +The {surveydown} R package provides functions to bring this all together. + +**See the [complete documentation](https://surveydown.org) to get started making your own surveydown survey!** ## Why surveydown? -```{r child="man/rmdchunks/motivation.Rmd"} -``` +Most survey platforms (e.g., Google forms, Qualtrics, etc.) use graphic interfaces or spreadsheets to define survey content, making version control, collaboration, and reproducibility difficult or impossible. The surveydown package was designed to address these problems. As an open-source, markdown-based platform, all survey content is defined using **plain text** (markdown and R code) in two files: + +- `survey.qmd`: A Quarto document that contains the survey content (pages, questions, etc). +- `app.R`: An R script defining a shiny app that contains global settings (libraries, database configuration, etc.) and server configuration options (e.g., conditional skipping / display, etc.). + +This approach makes your survey easy to reproduce, share, and version control with common tools like Git. And since all survey data is stored in a PostgreSQL database, you have total control over where your survey data lives. We provide direct support for [Supabase](https://supabase.com/) as a free, secure, and easy to use option. + +In case you're interested in the background behind the project, this [blog post](https://www.jhelvy.com/blog/2023-04-06-markdown-surveys/) provides something of an origin story. Note that the design discussed in the post is now quite outdated with what ultimately became surveydown. ## Installation ### Install R & Quarto -```{r child="man/rmdchunks/install_R_Quarto.Rmd"} -``` +You need both: + +- Install [R](https://CRAN.R-project.org/) +- Install [Quarto](https://quarto.org/) + +We also recommend working with an IDE that has good support for R, Quarto, and Shiny. + +[RStudio](https://posit.co/products/open-source/rstudio/) is great, and we also like [VSCode](https://github.com/microsoft/vscode) and [Positron](https://github.com/posit-dev/positron). ### Install the {surveydown} R package -```{r child="man/rmdchunks/install_surveydown.Rmd"} +You can install {surveydown} from CRAN in your R console: + +```{r} +#| eval: false + +install.packages("surveydown") ``` -## Roadmap +or you can install the development version from [GitHub](https://github.com/surveydown-dev/surveydown): + +```{r} +#| eval: false + +# install.packages("pak") +pak::pak('surveydown-dev/surveydown') +``` + +Load the package with: + +```{r} +#| eval: false -```{r child="man/rmdchunks/todo.Rmd"} +library(surveydown) ``` +You can also check which version you have installed: + +```{r} +#| eval: false + +surveydown::sd_version() +``` + +## Roadmap + +See our [todo](https://github.com/surveydown-dev/todo) repo for a running list of things we're working on / have already added to the project. + ## License See the [License](https://github.com/surveydown-dev/surveydown/blob/master/LICENSE.md). diff --git a/README.md b/README.md index adcb507..6608308 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,7 @@ with [R](https://www.r-project.org/), [Quarto](https://quarto.org/),
-
image showing the three technologies used in the surveydown platform along with their logos: quarto (for designing surveys), shiny (for rendering the survey), and supabase (for storing data) -
diff --git a/man/rmdchunks/concept.Rmd b/man/rmdchunks/concept.Rmd deleted file mode 100644 index 2ea8240..0000000 --- a/man/rmdchunks/concept.Rmd +++ /dev/null @@ -1,19 +0,0 @@ -**surveydown** is a flexible, open-source platform for making surveys with [R](https://www.r-project.org/), [Quarto](https://quarto.org/), [Shiny](https://shiny.posit.co/), and [Supabase](https://supabase.com/). - -
-
-image showing the three technologies used in the surveydown platform along with their logos: quarto (for designing surveys), shiny (for rendering the survey), and supabase (for storing data) -
-
- -
- -Here's how it works: - -1. Design your survey as a [Quarto](https://quarto.org/) document using markdown and R code. -2. Render your survey into a [shiny](https://shiny.posit.co/) app that can be hosted online and sent to respondents. -3. Store survey responses in a PostgreSQL database - we recommend [Supabase](https://supabase.com/) as a free, secure, and easy to use option. - -The {surveydown} R package provides functions to bring this all together. - -**See the [complete documentation](https://surveydown.org) to get started making your own surveydown survey!** diff --git a/man/rmdchunks/install_R_Quarto.Rmd b/man/rmdchunks/install_R_Quarto.Rmd deleted file mode 100644 index 70e5fbe..0000000 --- a/man/rmdchunks/install_R_Quarto.Rmd +++ /dev/null @@ -1,8 +0,0 @@ -You need both: - -- Install [R](https://CRAN.R-project.org/) -- Install [Quarto](https://quarto.org/) - -We also recommend working with an IDE that has good support for R, Quarto, and Shiny. - -[RStudio](https://posit.co/products/open-source/rstudio/) is great, and we also like [VSCode](https://github.com/microsoft/vscode) and [Positron](https://github.com/posit-dev/positron). diff --git a/man/rmdchunks/install_surveydown.Rmd b/man/rmdchunks/install_surveydown.Rmd deleted file mode 100644 index 378f20b..0000000 --- a/man/rmdchunks/install_surveydown.Rmd +++ /dev/null @@ -1,32 +0,0 @@ -You can install {surveydown} from CRAN in your R console: - -```{r} -#| eval: false - -install.packages("surveydown") -``` - -or you can install the development version from [GitHub](https://github.com/surveydown-dev/surveydown): - -```{r} -#| eval: false - -# install.packages("pak") -pak::pak('surveydown-dev/surveydown') -``` - -Load the package with: - -```{r} -#| eval: false - -library(surveydown) -``` - -You can also check which version you have installed: - -```{r} -#| eval: false - -surveydown::sd_version() -``` diff --git a/man/rmdchunks/motivation.Rmd b/man/rmdchunks/motivation.Rmd deleted file mode 100644 index c375c49..0000000 --- a/man/rmdchunks/motivation.Rmd +++ /dev/null @@ -1,8 +0,0 @@ -Most survey platforms (e.g., Google forms, Qualtrics, etc.) use graphic interfaces or spreadsheets to define survey content, making version control, collaboration, and reproducibility difficult or impossible. The surveydown package was designed to address these problems. As an open-source, markdown-based platform, all survey content is defined using **plain text** (markdown and R code) in two files: - -- `survey.qmd`: A Quarto document that contains the survey content (pages, questions, etc). -- `app.R`: An R script defining a shiny app that contains global settings (libraries, database configuration, etc.) and server configuration options (e.g., conditional skipping / display, etc.). - -This approach makes your survey easy to reproduce, share, and version control with common tools like Git. And since all survey data is stored in a PostgreSQL database, you have total control over where your survey data lives. We provide direct support for [Supabase](https://supabase.com/) as a free, secure, and easy to use option. - -In case you're interested in the background behind the project, this [blog post](https://www.jhelvy.com/blog/2023-04-06-markdown-surveys/) provides something of an origin story. Note that the design discussed in the post is now quite outdated with what ultimately became surveydown. diff --git a/man/rmdchunks/todo.Rmd b/man/rmdchunks/todo.Rmd deleted file mode 100644 index 54f6778..0000000 --- a/man/rmdchunks/todo.Rmd +++ /dev/null @@ -1 +0,0 @@ -See our [todo](https://github.com/surveydown-dev/todo) repo for a running list of things we're working on / have already added to the project. diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 4a2eeb9..562f141 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -1,8 +1,15 @@ url: https://pkg.surveydown.org/ +navbar: + structure: + left: [docs, reference, articles, tutorials, news] + right: [github] + components: + docs: + text: Documentation + href: https://www.surveydown.org/ home: - title: Build markdown-based surveys with quarto shiny documents - + title: Markdown-Based Surveys Using R, Quarto, and Shiny template: bootstrap: 5 light-switch: true @@ -15,18 +22,15 @@ template: image: src: https://pkg.surveydown.org/reference/figures/logo.png alt: "Logo for the surveydown package" - reference: - title: Survey Data contents: - sd_database - sd_get_data - - title: Control Logic contents: - sd_show_if - sd_skip_if - - title: Server contents: - sd_server @@ -37,7 +41,6 @@ reference: - sd_copy_value - sd_get_url_pars - sd_is_answered - - title: Survey UI contents: - sd_question @@ -50,7 +53,6 @@ reference: - sd_display_question - sd_display_value - sd_ui - - title: Utilities contents: - sd_create_survey @@ -59,7 +61,6 @@ reference: - sd_setup - sd_add_page - sd_add_question - - title: Version Control contents: - sd_version diff --git a/vignettes/surveydown.Rmd b/vignettes/surveydown.Rmd deleted file mode 100644 index 2490ec9..0000000 --- a/vignettes/surveydown.Rmd +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "Introduction to surveydown" -description: > - Learn how to get started with the basics of surveydown. -output: rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{Introduction to surveydown} - %\VignetteEngine{knitr::rmarkdown} - \usepackage[utf8]{inputenc} ---- - -```{r setup, include=FALSE, message=FALSE, warning=FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - warning = FALSE, - message = FALSE, - eval = FALSE, - fig.retina = 3, - comment = "#>" -) -``` - -# Main Documentation - -The main documentation for surveydown is at [https://surveydown.org/](https://surveydown.org/). We recommend navigating there for more detailed documentation about the R package and how to use it to build dynamic surveys. - -## Overview - -Every surveydown survey is composed of a _survey_ and an _app_, defined in two separate files: - -- `survey.qmd`: A Quarto document that contains the survey content (pages, questions, etc), which renders to an HTML file. -- `app.R`: An R script defining a Shiny app that contains the global settings (libraries, database configuration, etc.) and server configuration options (e.g., conditional skipping / display, etc.). - -**These files must be named `survey.qmd` and `app.R`**. - -The [{surveydown}](https://pkg.surveydown.org) R package provides a set of functions for defining the survey content and configuration options. Each function starts with `sd_` to make them easy to identify. - -The platform is based on some basic principles: - -- Add content to your `survey.qmd` file using markdown text (or in RStudio use the visual editor). -- Define survey questions in R code chunks with the `sd_question()` function. -- Define pages using fences (`:::`), with navigation buttons handled using the `sd_next()` function. -- Add rich functionality to your survey using a variety of [server options](https://surveydown.org/server-options) and [conditional control logic](https://surveydown.org/conditional-control) in the `server()` function in the `app.R` file. -- Store your respondent data in a database (see [Store Data](https://surveydown.org/store-data)). - -This approach ensures a flexible survey platform that is fully reproducible and easy to customize. - -The remaining steps on this page will guide you through the process of creating a surveydown survey. - -## 1. Installation - -### Install R & Quarto - -- [R](https://CRAN.R-project.org/) -- [Quarto](https://quarto.org/) - -We also recommend working with an IDE that has good support for R, Quarto, and Shiny. [RStudio](https://posit.co/products/open-source/rstudio/) is great, and we also like [VSCode](https://github.com/microsoft/vscode) and [Positron](https://github.com/posit-dev/positron). - -### Install the {surveydown} R package - -You can install {surveydown} from CRAN in your R console: - -```{r} -#| eval: false - -install.packages("surveydown") -``` - -or you can install the development version from [GitHub](https://github.com/surveydown-dev/surveydown): - -```{r} -#| eval: false - -# install.packages("pak") -pak::pak('surveydown-dev/surveydown') -``` - -Load the package with: - -```{r} -#| eval: false - -library(surveydown) -``` - -You can also check which version you have installed: - -```{r} -#| eval: false - -surveydown::sd_version() -``` - -## 2. Start with a template - -See the [Template](https://surveydown.org/template) page. - -## 3. Add survey content in your `survey.qmd` file - -See the [Survey Components](https://surveydown.org/survey-components) page for details on the main components in a surveydown survey. For a quick overview, here's how you add pages and questions: - -- Add pages with fences, like this: - -``` -::: {#page1 .sd-page} - -Page 1 content here - -::: -``` - -- Add questions with the `sd_question()` function in code chunks (see the [Question Types](https://surveydown.org/question-types) page for more on the types of questions supported). For example, here's a multiple choice question: - -```{r} -#| eval: false - -sd_question( - type = 'mc', - id = 'penguins', - label = "Which is your favorite type of penguin?", - option = c( - 'Adélie' = 'adelie', - 'Chinstrap' = 'chinstrap', - 'Gentoo' = 'gentoo' - ) -) -``` - -## 4. Add control options - -In the `server()` function in the `app.R` file, add rich functionality to your survey using a variety of [server options](https://surveydown.org/server-options) and [conditional control logic](https://surveydown.org/conditional-control). - -## 5. Setup your database - -In the global settings at the top of the `app.R` file, setup your database with the `sd_database()` function. You can also leave it blank to preview / edit your survey without database connected, or set `ignore = TRUE` to run the survey without storing data. See the [Store Data](https://surveydown.org/store-data) page for more details. - -## 6. Locally preview - -Preview your survey by clicking the "Run App" button in RStudio or in your R console running the `runApp()` command. - -## 7. Deploy - -Deploy your survey by hosting it on your favorite server, like {{< var shinyapps >}}, {{< var huggingface >}}, [Posit Connect Cloud](https://connect.posit.cloud/), [Heroku](https://www.heroku.com/), etc. See the [Deployment](https://surveydown.org/deployment) page for more details.