Merge pull request #159 from hyperweb-io/anmol/docs

docs: add docs from docs repo to product repo, add gh-action to sync repos

Author: Anmol1696

.github/workflows/docs.yaml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yaml"
+
+env:
+  # Repository specific variables
+  REPO_NAME: ts-codegen
+  DOCS_DEST_PATH: pages/ts-codegen
+
+jobs:
+  docs-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          enable-global-cache: true
+
+      - name: Clone docs repository
+        run: git clone https://x-access-token:${{ secrets.GH_HYPERWEB_PAT }}@github.com/hyperweb-io/docs.hyperweb.io.git external-docs
+
+      - name: Sync the docs and build
+        run: |
+          rsync -av --delete ./docs/ ./external-docs/${{ env.DOCS_DEST_PATH }}/
+          cd external-docs
+          yarn install
+          yarn export
+
+      - name: Git push
+        run: |
+          cd external-docs
+          git config user.name 'GitHub Action'
+          git config user.email '[email protected]'
+          git add .
+          if git diff --cached --quiet; then
+              echo "No changes to commit."
+          else
+              git commit -m "Automated: Update ${{ env.REPO_NAME }} documentation"
+              git push
+          fi
+

docs/_meta.json

@@ -0,0 +1,4 @@
+{
+  "index": "Introduction",
+  "developing": "Developing"
+}

docs/developing/_meta.json

@@ -0,0 +1,4 @@
+{
+  "index": "Developing",
+  "ast": "Working with ASTs"
+}

docs/developing/ast.mdx

@@ -0,0 +1,128 @@
+## Working with ASTs
+
+### 1 edit the fixture
+
+edit `./scripts/fixture.ts`, for example:
+
+```js
+// ./scripts/fixture.ts
+export interface InstantiateMsg {
+    admin?: string | null;
+    members: Member[];
+}
+```
+
+### 2 run AST generator
+
+```
+yarn test:ast
+```
+
+### 3 look at the JSON produced
+
+```
+code ./scripts/test-output.json
+```
+
+We use the npm module `ast-stringify` to strip out unnecessary props, and generate a JSON for reference.
+
+You will see a `File` and `Program`... only concern yourself with the `body[]`:
+
+```json
+{
+  "type": "File",
+  "errors": [],
+  "program": {
+    "type": "Program",
+    "sourceType": "module",
+    "interpreter": null,
+    "body": [
+      {
+        "type": "ExportNamedDeclaration",
+        "exportKind": "type",
+        "specifiers": [],
+        "source": null,
+        "declaration": {
+          "type": "TSInterfaceDeclaration",
+          "id": {
+            "type": "Identifier",
+            "name": "InstantiateMsg"
+          },
+          "body": {
+            "type": "TSInterfaceBody",
+            "body": [
+              {
+                "type": "TSPropertySignature",
+                "key": {
+                  "type": "Identifier",
+                  "name": "admin"
+                },
+                "computed": false,
+                "optional": true,
+                "typeAnnotation": {
+                  "type": "TSTypeAnnotation",
+                  "typeAnnotation": {
+                    "type": "TSUnionType",
+                    "types": [
+                      {
+                        "type": "TSStringKeyword"
+                      },
+                      {
+                        "type": "TSNullKeyword"
+                      }
+                    ]
+                  }
+                }
+              },
+              {
+                "type": "TSPropertySignature",
+                "key": {
+                  "type": "Identifier",
+                  "name": "members"
+                },
+                "computed": false,
+                "typeAnnotation": {
+                  "type": "TSTypeAnnotation",
+                  "typeAnnotation": {
+                    "type": "TSArrayType",
+                    "elementType": {
+                      "type": "TSTypeReference",
+                      "typeName": {
+                        "type": "Identifier",
+                        "name": "Member"
+                      }
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    ],
+    "directives": []
+  },
+  "comments": []
+}
+```
+
+### 4 code with `@babel/types` using the JSON as a reference
+
+NOTE: 4 continued ideally you should be writing a test with your generator!
+
+```js
+import * as t from '@babel/types';
+
+export const createNewGenerator = () => {
+    return t.exportNamedDeclaration(
+        t.tsInterfaceDeclaration(
+            t.identifier('InstantiateMsg'),
+            null,
+            [],
+            t.tsInterfaceBody([
+                // ... more code ...
+            ])
+        )
+    );
+};
+```

docs/developing/index.mdx

@@ -0,0 +1,27 @@
+# Developing
+
+## Initial setup
+
+```
+yarn
+yarn bootstrap
+```
+
+## Building
+
+```
+yarn build
+```
+
+## Tests
+
+Then `cd` into a package and run the tests
+
+```
+cd ./packages/wasm-ast-types
+yarn test:watch
+```
+
+## Working with ASTs
+
+See the [docs](/ts-codegen/developing/ast) in the `wasm-ast-types` package.