Skip to content

Commit 1893114

Browse files
katelynsillstyg
katelynsills
and
tyg
authored
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]>
1 parent 8abe577 commit 1893114

File tree

13 files changed

+2743
-442
lines changed

13 files changed

+2743
-442
lines changed

‎.github/workflows/test-build.yml

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -26,18 +26,3 @@ jobs:
2626
root: main/.vuepress/dist
2727
extra: --ignore_re r'\ADuplicate ID "outbound-link-title".*'
2828

29-
- name: Set up Python 3.7
30-
uses: actions/setup-python@v1
31-
with:
32-
python-version: 3.7
33-
- name: Install dependencies
34-
run: |
35-
python -m pip install --upgrade pip setuptools
36-
python -m pip install pyspelling
37-
- name: Install Aspell
38-
run: |
39-
sudo apt-get install aspell aspell-en
40-
41-
- name: Spell check
42-
run: |
43-
python -m pyspelling

‎.github/workflows/test-snippets.yml

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Lint and Test Snippets
2+
3+
# run CI on pushes to master, and on all PRs (even the ones that target other
4+
# branches)
5+
6+
on:
7+
push:
8+
branches: [master]
9+
pull_request:
10+
11+
jobs:
12+
build:
13+
runs-on: ubuntu-latest
14+
strategy:
15+
matrix:
16+
node-version: [14.x]
17+
steps:
18+
- name: Checkout
19+
uses: actions/checkout@v2
20+
21+
# Select a branch on agoric-sdk to test against by adding text to the body of the
22+
# pull request. For example: #agoric-sdk-branch: zoe-release-0.7.0
23+
# The default is 'master'
24+
- name: Get the appropriate agoric-sdk branch
25+
id: get-branch
26+
uses: actions/[email protected]
27+
with:
28+
result-encoding: string
29+
script: |
30+
const { body = '' } = context.payload.pull_request || {};
31+
const regex = /.*\#agoric-sdk-branch:\s+(\S+)/;
32+
const match = regex.exec(body);
33+
const agoricSdkBranch = match && match[1] || 'master';
34+
console.log(agoricSdkBranch);
35+
return agoricSdkBranch;
36+
37+
- name: Checkout agoric-sdk
38+
uses: actions/checkout@v2
39+
with:
40+
repository: Agoric/agoric-sdk
41+
path: agoric-sdk
42+
ref: ${{steps.get-branch.outputs.result}}
43+
44+
- name: Use Node.js ${{ matrix.node-version }}
45+
uses: actions/setup-node@v1
46+
with:
47+
node-version: ${{ matrix.node-version }}
48+
49+
- name: Setup and link agoric-sdk packages
50+
run: |
51+
yarn install
52+
yarn build
53+
yarn link-cli ~/bin/agoric
54+
echo "::add-path::/home/runner/bin"
55+
working-directory: ./agoric-sdk
56+
57+
- name: agoric install
58+
run: agoric install
59+
- name: yarn lint
60+
run: yarn lint
61+
- name: yarn test snippets
62+
run: yarn test

‎.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
node_modules/
22
dist/
3-
.DS_Store
3+
.DS_Store
4+
_agstate

‎.pyspelling.yml

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
matrix:
2-
- name: Markdown
2+
- name: html
33
aspell:
44
lang: en
55
dictionary:
@@ -9,8 +9,7 @@ matrix:
99
pipeline:
1010
- pyspelling.filters.html:
1111
ignores:
12-
- code
13-
- pre
12+
- div
1413
sources:
1514
- 'main/.vuepress/dist/**/*.html'
1615
default_encoding: utf-8

‎.wordlist.txt

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,10 @@ aliceMoolaGainAmount
3232
aliceMoolaPayment
3333
aliceMoolaPayout
3434
aliceMoolaPurse
35+
aliceOffer
3536
alicePayment
3637
alicePayments
38+
alicePayout
3739
alicePricePayout
3840
aliceProposal
3941
aliceQuatloosDepositFacet
@@ -95,7 +97,9 @@ assuranceMath
9597
async
9698
asynchronicity
9799
atomicSwap
100+
atomicSwapBundle
98101
atomicSwapDescription
102+
atomicSwapInstallation
99103
atomicSwapInstance
100104
automaticRefund
101105
autoswap
@@ -179,6 +183,7 @@ conf
179183
config
180184
const
181185
ContractFacet
186+
contractFormat
182187
ContractHost
183188
contractHost
184189
contractOfferPromise
@@ -244,12 +249,14 @@ encourageMe
244249
encouragementBot
245250
encouragementinstallation
246251
enduser
252+
endregion
247253
ertp
248254
ERTP
249255
ERTP's
250256
escrowed
251257
Escrowing
252258
escrowing
259+
Ethereum
253260
Eval
254261
exampleAmountMath
255262
exampleBrand
@@ -275,6 +282,7 @@ getBalance
275282
getBrand
276283
getBrandForIssuer
277284
getBrands
285+
getBundle
278286
getCalls
279287
getCurrentAllocation
280288
getCurrentAmount
@@ -305,6 +313,7 @@ getOfferResult
305313
getOffers
306314
getOutPutPrice
307315
getOutputPrice
316+
getPayments
308317
getPayout
309318
getPayouts
310319
getPoolAllocation
@@ -341,8 +350,10 @@ IDEs
341350
idToOfferHandle
342351
iframe
343352
implementating
353+
importBundleSource
344354
init
345355
inspectable
356+
inspectCode
346357
installationConstants
347358
installationHandle
348359
installationP
@@ -358,6 +369,7 @@ invitationP
358369
invitationValue
359370
inviteIssuer
360371
inviteP
372+
isCorrectCode
361373
isEmpty
362374
isEqual
363375
isGTE
@@ -479,6 +491,7 @@ newPayment
479491
newState
480492
nft
481493
NFTs
494+
nonfungible
482495
npm
483496
NUM
484497
numBids
@@ -510,6 +523,7 @@ otherAmountMath
510523
otherIssuer
511524
otherMint
512525
otherPayment
526+
ourProposal
513527
overpayment
514528
params
515529
pathResolve
@@ -522,6 +536,7 @@ paymentKeywordRecordPromise
522536
PaymentPKeywordRecord
523537
paymentsArray
524538
paymentToBurn
539+
permalink
525540
Petname
526541
petname
527542
petnameOrPath
@@ -707,6 +722,7 @@ tradable
707722
Triskelion
708723
tryExit
709724
tv
725+
txt
710726
TypeError
711727
TypeScript
712728
ui
@@ -749,6 +765,7 @@ WebSockets
749765
WebStorm
750766
withdrawalPayment
751767
Woohoo
768+
wordlist
752769
wsl
753770
xSeat
754771
YAML
@@ -766,6 +783,4 @@ ZoeHelper
766783
ZoeHelpers
767784
zoeHelpers
768785
ZoeService
769-
zoeService
770-
txt
771-
wordlist
786+
zoeService

‎CONTRIBUTING.md

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
1+
## Install
2+
Run `agoric install` to ensure that we are using the latest version of
3+
agoric-sdk when we run our code snippets.
4+
15
## Build Locally
26

37
To run a local server to see the changes in real time, run:
48

59
```shell
6-
npm run docs:dev
10+
yarn docs:dev
711
```
812

913
Note that changes to the site config may require stopping this program
@@ -12,7 +16,7 @@ and restarting.
1216
To build the site as it will be built for production, run:
1317

1418
```shell
15-
npm run docs:build
19+
yarn docs:build
1620
```
1721

1822
## Github Actions and Continuous Integration
@@ -22,7 +26,11 @@ Github Actions run:
2226

2327
* Test the build - This tests that the build does not have any errors and
2428
that the result passes HTML5 validation
25-
* Spellcheck - This checks the Markdown documents against a dictionary and a local wordlist
29+
* Spellcheck - This checks the Markdown documents against a dictionary
30+
and a local wordlist
31+
* Lint and Test Snippets - This tests the code snippets that are
32+
imported into the documentation. Note that code included inline does
33+
not get tested or run.
2634

2735
## Spellcheck
2836

@@ -33,6 +41,27 @@ in `Agoric/documentation/.wordlist.txt`. Please maintain the list's alphabetical
3341

3442
![](./contributing-assets/spellcheck-results.png)
3543

44+
## Importing and testing snippets
45+
46+
To import code snippets into the documentation, you can write up the
47+
code in a separate file under `snippets/`, then include it by adding a
48+
line like `<<< @/snippets/test-intro-zoe.js#install` to your document.
49+
The section `test-intro-zoe.js` should be replaced with your
50+
particular filename. `#install` is an example of a specific code
51+
region in the file to import. For example, it might look like:
52+
53+
```js
54+
// #region install
55+
const atomicSwapInstallation = await E(zoe).install(atomicSwapBundle);
56+
// #endregion install
57+
```
58+
59+
Write tests using AVA, and then run them with `yarn test`. The code
60+
files can also be linted with `yarn lint-fix`. Testing code snippets
61+
allows us to ensure that our documents are using real code that works
62+
with the current version of agoric-sdk (whatever is on master) and is
63+
not outdated.
64+
3665
## Check Links
3766

3867
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.

‎_agstate/empty.js

Whitespace-only changes.

0 commit comments

Comments
 (0)