Last tweaks.

coatless · Sep 17, 2023 · 046554d · 046554d
1 parent 77fc729
commit 046554d
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 37 deletions.
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -42,6 +42,8 @@ website:
             text: Troubleshooting
           - href: webr-developer-resources.qmd
             text: Developer Resources
+          - href: webr-extension-website.qmd
+            text: Setting up the Extension Website
           - href: webr-acknowledgements.md
             text: Acknowledgements
 

diff --git a/docs/webr-developer-resources.qmd b/docs/webr-developer-resources.qmd
@@ -16,7 +16,9 @@ Before diving into extension development, it's essential to understand the core
 
 - **[webR Documentation](https://docs.r-wasm.org/webr/latest/)**: This comprehensive documentation is your gateway to a deep understanding of webR. It provides profound insights into webR's features, usage, and capabilities. Dive into practical examples, comprehensive guides, and everything you need to become a webR expert.
 
-- **[webR Source Code](https://github.com/r-wasm/webr/)**: For the technically curious, our GitHub source code repository offers transparency into the development process of webR. Here, you can review, contribute, and engage with the vibrant webR community to enhance its capabilities.
+- **[webR Source Code](https://github.com/r-wasm/webr/)**: For the technically curious, webR's GitHub source code repository offers transparency into the development of webR. Here, you can review, contribute, and engage with the vibrant webR community to enhance its capabilities.
+
+- **[Bob Rudis' Experiments with webR](https://rud.is/webr-experiments/)**: Many different projects that explore a variety of use cases for webR. These experiments make use of the underlying webR JavaScript API.
 
 These resources empower you to master webR, whether you're just starting out or you're a seasoned developer eager to contribute. Remember, webR is a versatile tool that can be used independently or alongside the Quarto extension to unlock the magic of interactive code cells in HTML documents.
 

diff --git a/docs/webr-extension-website.qmd b/docs/webr-extension-website.qmd
@@ -0,0 +1,41 @@
+---
+title: "Quarto Extension Website Guide"
+subtitle: "Development notes for the quarto-webr website"
+author: "James Joseph Balamuta"
+date: "09-17-2023"
+date-modified: last-modified
+format: 
+  html:
+    toc: true
+---
+
+# Initializing the Project
+
+To get started, follow these steps to set up the Quarto extension website project:
+
+1. Create a new directory named `docs/` within your repository using the following command:
+
+   ```sh
+   mkdir docs && cd $_
+   ```
+
+2. Initialize a Quarto website project by running the following command:
+
+   ```sh
+   quarto create project website .
+   ```
+
+# Incorporating the Extension
+
+To seamlessly integrate the extension into your project, you'll need to create a symbolic link to the `_extensions` folder containing the development version of the extension. This approach helps you avoid maintaining a duplicate copy of the extension in your Git repository history.
+
+Follow these steps:
+
+1. Navigate to the `docs/` directory in your project.
+
+2. Create a symbolic link to the `_extensions` folder using the following command:
+
+   ```sh
+   ln -s ../_extensions _extensions
+   ```
+
diff --git a/docs/webr-internal-cell.qmd b/docs/webr-internal-cell.qmd
@@ -22,26 +22,26 @@ Withholding code from the user requires the use of a custom `quarto-webr` cell o
 
 There are three different contexts supported by `quarto-webr`. By default, the `interactive` context is used if the `context` option is not specified in the code cell. These options are summarized in the table below:
 
-| `quarto-webr` Context | Quarto Cell Option | Description |
-|-----------------------|--------------------|-------------|
-| `interactive` (default) | `include: true` | Show both code and results |
-| `output` | `echo: false` | Suppress showing code, but display the results |
-| `setup` | `include: false` | Suppress showing both code and results |
+| `quarto-webr` Context   | Quarto Cell Option | Description                                    |
+|-------------------------|--------------------|------------------------------------------------|
+| `interactive` (default) | `include: true`    | Show both code and results                     |
+| `output`                | `echo: false`      | Suppress showing code, but display the results |
+| `setup`                 | `include: false`   | Suppress showing both code and results         |
 
 ::: {.callout-caution}
 Please note that the contents of the hidden code cell can be viewed if the web page's source code is inspected.
 :::
 
-## Hidden Evaluation without Output
+## "setup" - Hidden Evaluation and Output
 
-You can create a hidden setup code cell within the document by using the special comment `#| context: setup`. The code in this cell executes in the background without displaying the code or its output.
+You can create hidden setup code cells within your document using the special comment `#| context: setup`. The code within these cells executes discreetly in the background without displaying the code or its output.
 
 ```{{webr-r}}
 #| context: setup
 meaning_of_life = 42
 ```
 
-In the above example, we've pre-loaded the `meaning_of_life` variable. If we run the next code cell, you will see the value of `meaning_of_life` displayed as `42`.
+In the example above, we've pre-loaded the `meaning_of_life` variable with a value of `42`. If you proceed to run the subsequent code cell, you'll observe the value of `meaning_of_life` being displayed as `42`.
 
 ```{webr-r}
 #| context: setup
@@ -52,32 +52,29 @@ meaning_of_life = 42
 meaning_of_life
 ```
 
-## Hidden Evaluation without Output
+By incorporating the `setup` hidden code cell for data loading and preprocessing, you enhance the user experience by providing them with an accessible and interactive environment for working with the data while maintaining a clutter-free and organized document structure.
 
-In `quarto-webr`, you have the capability to create hidden setup code cells within your document using the special comment `#| context: setup`. The code within these cells executes discreetly in the background without displaying the code or its output.
 
-```{webr-r}
-#| context: setup
-meaning_of_life = 42
-```
+## "output" - Hidden Evaluation with Results Shown
 
-In the example above, we've pre-loaded the `meaning_of_life` variable with a value of `42`. If you proceed to run the subsequent code cell, you'll observe the value of `meaning_of_life` being displayed as `42`.
+You also have the choice of crafting an output-only code cell within your `quarto-webr` document, achieved by incorporating the special comment `#| context: output`. The code inside this cell executes quietly in the background and reveals its output when the execution is complete. The output can take the form of either text or graphics.
 
-```{webr-r}
-#| context: setup
-meaning_of_life = 42
+For instance, the following code cell suppresses the creation of the matrix; but, displays the end result.
+
+```{{webr-r}}
+#| context: output
+mat2x2 <- matrix(c(1, 2, 3, 4), nrow = 2)
+mat2x2
 ```
 
 ```{webr-r}
-meaning_of_life
+#| context: output
+mat2x2 <- matrix(c(1, 2, 3, 4), nrow = 2)
+mat2x2
 ```
 
-By incorporating the `setup` hidden code cell for data loading and preprocessing, you enhance the user experience by providing them with an accessible and interactive environment for working with the data while maintaining a clutter-free and organized document structure.
-
-
-## Hidden Evaluation with Output
 
-You also have the choice of crafting an output-only code cell within your `quarto-webr` document, achieved by incorporating the special comment `#| context: output`. The code inside this cell executes quietly in the background and reveals its output when the execution is complete. The output can take the form of either text or graphics.
+In the next example, the code used to generate the graph is suppressed. 
 
 ```{{webr-r}}
 #| context: output
@@ -105,16 +102,6 @@ plot(
 )
 ```
 
-```{{webr-r}}
-#| context: output
-matrix(c(1, 2, 3, 4), nrow = 2)
-```
-
-```{webr-r}
-#| context: output
-matrix(c(1, 2, 3, 4), nrow = 2)
-```
-
 By using `output` code cells, you maintain a streamlined and comprehensible document, focusing on the outcome rather than the intricate data processing steps. This approach will enhance the readability and clarity of your content, making it more accessible and informative to your audience.
 
 # Sample Cases
@@ -127,7 +114,7 @@ The `setup` hidden code cell is a powerful tool for seamlessly pre-loading and p
 
 In the following example, we demonstrate the process of loading and preprocessing a dataset. First, we download the dataset from an external source and save it as `'penguins.csv'` in the virtual webR file system. Next, we read the data into a data frame named `df_penguins`. All these operations occur silently in the background, ensuring that your document remains clean and focused on the data's application.
 
-```{webr-r}
+```{{webr-r}}
 #| context: setup
 
 # Download a dataset
@@ -171,7 +158,7 @@ webr:
 Learn more on the [Using R Packages](webr-using-r-packages.qmd) documentation page.
 :::
 
-### Hidden Summarization
+## Hidden Summarization
 
 You can use the output hidden code cell to generate summarized information about retrieved or manipulated data. This powerful feature enables you to process and summarize data without displaying the intermediary steps or code, keeping your document clean and focused on the results.