feat: github action to integrate/publish endo and agoric-sdk referenc…

…e docs too (#1038)

* feat: github action to integrate/publish endo reference doc too

* feat: refine build steps and add steps to build agoric-sdk docs

* debug: add `yarn build` like Dan suggested

* chore: bump vitepress to 1.0.1

* debug: add a DEBUG flag to "docs:build-cf" script

* chore: update ignoreDeadLinks list

* ci: update yarn commands to generate markdown files

* ci: update github workflow to reflect upstream changes

* ci: use cloudflare/pages-action instead and add a step to comment URL

* ci: switch back to using wrangler-action and use its output

* ci: add a condition to check if event is pull request

* ci: add conditions for preview and production deployments separately

* comment: add some background in comments for build-deploy-doc workflow

* chore: add endo and agoric-sdk to submodules

* ci: disable github workflow for now

* chore: bump node version to 18.18.0

* ci: add several yarn targets to build .md docs for endo and agoric-sdk

* chore: update submodules

* chore: add a yarn target for `git:update-submodules`

* debug: undo `yarn install` by cloudflare to build

* debug: update file paths when `mv`ing

* chore: add a comment for docs:build-cf script

* chore: add a yarn script for git-submodule:init

.github/workflows/build-deploy-doc.yml.DISABLED

@@ -1,57 +1,86 @@
-# Based on example at: https://github.com/marketplace/actions/deploy-to-github-pages
-
 name: Build and Deploy documentation site
+
+# This workflow is a customized workflow to deploy docs site to Cloudflare
+# The reason we can no longer use Cloudflare's git integration to deploy docs
+# site anymore is that Cloudflare's git integration would only check out
+# documentation repo, whereas we need to check out both `endojs/endo` and
+# `agoric/agoric-sdk` repo to build the docs site.
+
 on:
-  push:	
-    branches:	
+  # If it's a push to production branch, Cloudflare wrangler will deploy it as a
+  # production deployment
+  # The production branch for documentation project on Cloudflare is configured
+  # to be `main`
+  push:
+    branches:
       - main
+  # If it's a push to a non-production branch, Cloudflare wrangler will deploy
+  # it as a preview deployment
+  pull_request:
+    branches:
+      - "*"
+
 jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/[email protected]
+      uses: actions/checkout@v4
+
+    - name: Checkout Endo
+      uses: actions/checkout@v4
+      with:
+        repository: endojs/endo
+        path: endo
+
+    - name: Build Endo docs
+      run: |
+        cd endo
+        yarn install
+        yarn docs:markdown-for-agoric-documentation-repo
+
+    - name: Move Endo docs into main/reference
+      run: mv endo/api-docs main/reference/endo
+
+    - name: Checkout agoric-sdk
+      uses: actions/checkout@v4
       with:
-        persist-credentials: false
+        repository: agoric/agoric-sdk
+        path: agoric-sdk
 
-    - name: Install and Build
+    - name: Build agoric-sdk docs
       run: |
+        cd agoric-sdk
         yarn install
-        yarn docs:build
+        yarn build
+        yarn docs:markdown-for-agoric-documentation-repo
+
+    - name: Move agoric-sdk docs into main/reference
+      run: mv agoric-sdk/api-docs main/reference/agoric-sdk
 
-    - name: Configure SSH
+    - name: Build Doc site
       run: |
-        mkdir -m0700 -p ~/.ssh/
-        echo "$SSH_KEY" > ~/.ssh/staging.key
-        chmod 600 ~/.ssh/staging.key
-        cat >>~/.ssh/config <<END
-        Host staging
-          HostName $SSH_HOST
-          User $SSH_USER
-          IdentityFile ~/.ssh/staging.key
-          StrictHostKeyChecking no
-        Host staging2
-          HostName $SSH_HOST2
-          User $SSH_USER
-          IdentityFile ~/.ssh/staging.key
-          StrictHostKeyChecking no
-        END
-      env:
-        SSH_USER: ${{ secrets.STAGING_SSH_USER }}
-        SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
-        SSH_HOST: ${{ secrets.STAGING_SSH_HOST }}
-        SSH_HOST2: ${{ secrets.STAGING_SSH_HOST2 }}
-
-    - name: SSH check out and build (staging)
-      run: ssh staging 'cd documentation && git pull && yarn install --frozen-lockfile && yarn docs:build'
-
-    - name: SSH check out and build (staging2)
-      run: ssh staging2 'cd documentation && git pull && yarn install --frozen-lockfile && yarn docs:build'
-
-    - name: Deploy to gh-pages
-      uses: JamesIves/[email protected]
+        yarn install
+        yarn docs:build-cf
+
+    - name: Publish to Cloudflare Pages
+      id: publish-to-cloudflare-pages
+      uses: cloudflare/wrangler-action@v3
+      with:
+        apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        # Cloudflare account ID is safe to be public
+        # Ref: https://github.com/cloudflare/wrangler-legacy/issues/209#issuecomment-541654484
+        accountId: 0c4635effffcd7f36d1b9f0425a4367a
+        command: pages deploy --project-name=documentation dist/
+
+    - name: Comment with preview URL
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
       with:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Provided by github: https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#about-the-github_token-secret
-        BRANCH: gh-pages # The branch the action should deploy to.
-        FOLDER: main/.vitepress/dist # The folder the action should deploy
-        CLEAN: true # Automatically remove deleted files from the deploy branch
+        script: |
+          github.rest.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: 'Cloudflare Pages Preview URL: ${{ steps.publish-to-cloudflare-pages.outputs.deployment-url }}'
+          })

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "agoric-sdk"]
+	path = agoric-sdk
+	url = https://github.com/Agoric/agoric-sdk
+[submodule "endo"]
+	path = endo
+	url = https://github.com/endojs/endo

.node-version

@@ -1 +1 @@
-v18.17.0
+v18.18.0

main/.vitepress/config.mjs

@@ -83,6 +83,11 @@ export default defineConfig({
   ignoreDeadLinks: [
     // ignore all localhost links
     /^https?:\/\/localhost/,
+    // ignore links that starts with ./packages/*
+    /^.\/packages\/*/,
+    './MAINTAINERS',
+    './CONTRIBUTING',
+    './LICENSE',
   ],
   sitemap: {
     hostname: 'https://docs.agoric.com',

package.json

@@ -7,7 +7,12 @@
     "docs:dev": "NODE_OPTIONS=--openssl-legacy-provider vitepress dev main",
     "docs:build": "NODE_OPTIONS=--openssl-legacy-provider vitepress build main",
     "docs:preview": "NODE_OPTIONS=--openssl-legacy-provider vitepress preview main",
-    "docs:build-cf": "NODE_OPTIONS=--openssl-legacy-provider vitepress build main && cp _redirects dist/",
+    "docs:build-endo": "cd endo; yarn install; yarn docs:markdown-for-agoric-documentation-repo; mv api-docs ../main/reference/endo",
+    "docs:build-agoric-sdk": "cd agoric-sdk; yarn install; yarn build; yarn docs:markdown-for-agoric-documentation-repo; mv api-docs ../main/reference/agoric-sdk",
+    "//docs:build-cf": "echo 'XXX Cloudflare Pages deployment will automatically run `yarn install` right after `git clone`, but this will interfere with building markdown files for endo and agoric-sdk. So we remove node_modules directory before building markdown files and run `yarn install` before running vitepress'",
+    "docs:build-cf": "rm -rf node_modules; yarn docs:build-endo; yarn docs:build-agoric-sdk; yarn install; DEBUG='vitepress:*' NODE_OPTIONS=--openssl-legacy-provider vitepress build main && cp _redirects dist/",
+    "git-submodule:init": "git submodule init",
+    "git-submodule:update": "git submodule update --remote --merge",
     "test": "ava",
     "lint-fix": "yarn lint --fix",
     "lint": "eslint 'snippets/**/*.js'",
@@ -65,7 +70,7 @@
     "prettier": "^1.19.1",
     "ses": "^0.18.8",
     "stylus": "^0.62.0",
-    "vitepress": "^1.0.0-rc.42"
+    "vitepress": "^1.0.1"
   },
   "resolutions": {},
   "globals": {