chore: rewrite the Zoe introduction (#311)

* chore: rewrite the Zoe introduction * refactor: move code examples into snippets, add testing for snippets * test: add testing of code snippets to CI * chore: just test snippets on node 14. Heavy testing done in agoric-sdk * chore: add to wordlist * chore: add an empty agstate to allow us to use `agoric install` * chore: add information about code snippets to CONTRIBUTING.md. * chore: add words to wordlist * chore: address some PR comments * chore: address PR comments * chore: address PR comments * chore: try fixing spellchecker * chore: try fixing spellchecker again * chore: more spellchecker fixes * test only: skip div - should not catch anything * test only - skip div, should not catch anything * Update main/getting-started/intro-zoe.md Co-authored-by: Tom Galloway <[email protected]> * Update main/getting-started/intro-zoe.md Co-authored-by: Tom Galloway <[email protected]> * chore: address PR comments (somehow lost, after being committed from Github interface_ * Apply suggestions from code review Co-authored-by: Tom Galloway <[email protected]> * chore: address PR comments * chore: remove spellchecker for now Co-authored-by: Tom Galloway <[email protected]>
Agoric · Sep 29, 2020 · 1893114 · 1893114
1 parent 8abe577
commit 1893114
Show file tree

Hide file tree

Showing 13 changed files with 2,743 additions and 442 deletions.
diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml
@@ -26,18 +26,3 @@ jobs:
         root: main/.vuepress/dist
         extra: --ignore_re r'\ADuplicate ID "outbound-link-title".*'
 
-    - name: Set up Python 3.7
-      uses: actions/setup-python@v1
-      with:
-        python-version: 3.7
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip setuptools
-        python -m pip install pyspelling
-    - name: Install Aspell
-      run: |
-        sudo apt-get install aspell aspell-en
-
-    - name: Spell check
-      run: |
-        python -m pyspelling
diff --git a/.github/workflows/test-snippets.yml b/.github/workflows/test-snippets.yml
@@ -0,0 +1,62 @@
+name: Lint and Test Snippets
+
+# run CI on pushes to master, and on all PRs (even the ones that target other
+# branches)
+
+on:
+ push:
+   branches: [master]
+ pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [14.x]
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    # Select a branch on agoric-sdk to test against by adding text to the body of the
+    # pull request. For example: #agoric-sdk-branch: zoe-release-0.7.0
+    # The default is 'master'
+    - name: Get the appropriate agoric-sdk branch
+      id: get-branch
+      uses: actions/[email protected]
+      with:
+        result-encoding: string
+        script: |
+          const { body = '' } = context.payload.pull_request || {};
+          const regex = /.*\#agoric-sdk-branch:\s+(\S+)/;
+          const match = regex.exec(body);
+          const agoricSdkBranch = match && match[1] || 'master';
+          console.log(agoricSdkBranch);
+          return agoricSdkBranch;
+
+    - name: Checkout agoric-sdk
+      uses: actions/checkout@v2
+      with:
+        repository: Agoric/agoric-sdk
+        path: agoric-sdk
+        ref: ${{steps.get-branch.outputs.result}}
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+
+    - name: Setup and link agoric-sdk packages
+      run: |
+        yarn install
+        yarn build
+        yarn link-cli ~/bin/agoric
+        echo "::add-path::/home/runner/bin"
+      working-directory: ./agoric-sdk
+
+    - name: agoric install
+      run: agoric install
+    - name: yarn lint
+      run: yarn lint
+    - name: yarn test snippets
+      run: yarn test
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 node_modules/
 dist/
-.DS_Store
+.DS_Store
+_agstate
diff --git a/.pyspelling.yml b/.pyspelling.yml
@@ -1,5 +1,5 @@
 matrix:
-- name: Markdown
+- name: html
   aspell:
     lang: en
   dictionary:
@@ -9,8 +9,7 @@ matrix:
   pipeline:
   - pyspelling.filters.html:
     ignores:
-    - code
-    - pre
+    - div
   sources:
   - 'main/.vuepress/dist/**/*.html'
   default_encoding: utf-8
diff --git a/.wordlist.txt b/.wordlist.txt
@@ -32,8 +32,10 @@ aliceMoolaGainAmount
 aliceMoolaPayment
 aliceMoolaPayout
 aliceMoolaPurse
+aliceOffer
 alicePayment
 alicePayments
+alicePayout
 alicePricePayout
 aliceProposal
 aliceQuatloosDepositFacet
@@ -95,7 +97,9 @@ assuranceMath
 async
 asynchronicity
 atomicSwap
+atomicSwapBundle
 atomicSwapDescription
+atomicSwapInstallation
 atomicSwapInstance
 automaticRefund
 autoswap
@@ -179,6 +183,7 @@ conf
 config
 const
 ContractFacet
+contractFormat
 ContractHost
 contractHost
 contractOfferPromise
@@ -244,12 +249,14 @@ encourageMe
 encouragementBot
 encouragementinstallation
 enduser
+endregion
 ertp
 ERTP
 ERTP's
 escrowed
 Escrowing
 escrowing
+Ethereum
 Eval
 exampleAmountMath
 exampleBrand
@@ -275,6 +282,7 @@ getBalance
 getBrand
 getBrandForIssuer
 getBrands
+getBundle
 getCalls
 getCurrentAllocation
 getCurrentAmount
@@ -305,6 +313,7 @@ getOfferResult
 getOffers
 getOutPutPrice
 getOutputPrice
+getPayments
 getPayout
 getPayouts
 getPoolAllocation
@@ -341,8 +350,10 @@ IDEs
 idToOfferHandle
 iframe
 implementating
+importBundleSource
 init
 inspectable
+inspectCode
 installationConstants
 installationHandle
 installationP
@@ -358,6 +369,7 @@ invitationP
 invitationValue
 inviteIssuer
 inviteP
+isCorrectCode
 isEmpty
 isEqual
 isGTE
@@ -479,6 +491,7 @@ newPayment
 newState
 nft
 NFTs
+nonfungible
 npm
 NUM
 numBids
@@ -510,6 +523,7 @@ otherAmountMath
 otherIssuer
 otherMint
 otherPayment
+ourProposal
 overpayment
 params
 pathResolve
@@ -522,6 +536,7 @@ paymentKeywordRecordPromise
 PaymentPKeywordRecord
 paymentsArray
 paymentToBurn
+permalink
 Petname
 petname
 petnameOrPath
@@ -707,6 +722,7 @@ tradable
 Triskelion
 tryExit
 tv
+txt
 TypeError
 TypeScript
 ui
@@ -749,6 +765,7 @@ WebSockets
 WebStorm
 withdrawalPayment
 Woohoo
+wordlist
 wsl
 xSeat
 YAML
@@ -766,6 +783,4 @@ ZoeHelper
 ZoeHelpers
 zoeHelpers
 ZoeService
-zoeService
-txt
-wordlist
+zoeService
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,9 +1,13 @@
+## Install
+Run `agoric install` to ensure that we are using the latest version of
+agoric-sdk when we run our code snippets.
+
 ## Build Locally
 
 To run a local server to see the changes in real time, run:
 
 ```shell
-npm run docs:dev
+yarn docs:dev
 ```
 
 Note that changes to the site config may require stopping this program
@@ -12,7 +16,7 @@ and restarting.
 To build the site as it will be built for production, run:
 
 ```shell
-npm run docs:build
+yarn docs:build
 ```
 
 ## Github Actions and Continuous Integration
@@ -22,7 +26,11 @@ Github Actions run:
 
 * Test the build - This tests that the build does not have any errors and
   that the result passes HTML5 validation
-* Spellcheck - This checks the Markdown documents against a dictionary and a local wordlist
+* Spellcheck - This checks the Markdown documents against a dictionary
+  and a local wordlist
+* Lint and Test Snippets - This tests the code snippets that are
+  imported into the documentation. Note that code included inline does
+  not get tested or run. 
 
 ## Spellcheck
 
@@ -33,6 +41,27 @@ in `Agoric/documentation/.wordlist.txt`. Please maintain the list's alphabetical
 
 ![](./contributing-assets/spellcheck-results.png)
 
+## Importing and testing snippets
+
+To import code snippets into the documentation, you can write up the
+code in a separate file under `snippets/`, then include it by adding a
+line like `<<< @/snippets/test-intro-zoe.js#install` to your document.
+The section `test-intro-zoe.js` should be replaced with your
+particular filename. `#install` is an example of a specific code
+region in the file to import. For example, it might look like:
+
+```js
+  // #region install
+  const atomicSwapInstallation = await E(zoe).install(atomicSwapBundle);
+  // #endregion install
+```
+
+Write tests using AVA, and then run them with `yarn test`. The code
+files can also be linted with `yarn lint-fix`. Testing code snippets
+allows us to ensure that our documents are using real code that works
+with the current version of agoric-sdk (whatever is on master) and is
+not outdated.
+
 ## Check Links
 
 To check internal Vuepress links locally, run the following shell command. It does *not* check either external links or router-links. Output consists of the text of any broken links, what file they're in, and what line number they occur on.

diff --git a/_agstate/empty.js b/_agstate/empty.js