merge

dfinity · Sep 9, 2024 · 54a3e7f · 54a3e7f
1 parent 87060f7
commit 54a3e7f
Show file tree

Hide file tree

Showing 19 changed files with 630 additions and 579 deletions.
diff --git a/docs/developer-docs/backend/python/index.mdx b/docs/developer-docs/backend/python/index.mdx
@@ -20,6 +20,52 @@ Kybra allows developers to bring their existing Python skills and workflows to I
 Kybra is a community contributed project and is not maintained by DFINITY. Kybra is developed by [Demergent Labs](https://github.com/demergent-labs), a for-profit company that receives a grant from DFINITY for development of Kybra.
 :::
 
+## Using Kybra
+
+To use Kybra:
+
+- It is highly recommended that `dfx` commands should be run in a Python virtual environment that contains the `kybra` package.
+
+- The virtual environment **must** use the following dependencies and the exact versions listed:
+
+    - `dfx v0.19.0`
+
+    - Python `v3.10.7`
+
+To set up a Python virtual environment and install Kybra, use the following commands:
+
+<Tabs>
+<TabItem value={"linux"} label="Linux">
+```
+curl https://pyenv.run | bash
+~/.pyenv/bin/pyenv install 3.10.7
+~/.pyenv/versions/3.10.7/bin/python -m venv venv
+source venv/bin/activate
+pip install kybra
+```
+</TabItem>
+
+<TabItem value={"macos"} label="macOS">
+```
+brew install pyenv
+export PYENV_ROOT="$HOME/.pyenv"
+[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init -)"
+source ~/.zprofile
+pyenv install 3.10.7
+~/.pyenv/versions/3.10.7/bin/python -m venv venv
+source venv/bin/activate
+pip install kybra
+```
+</TabItem>
+
+<TabItem value={"windows"} label="Windows">
+
+Kybra is not currently supported on Windows. 
+
+</TabItem>
+</Tabs>
+
 ## Documentation
 
 - [Kybra Python CDK documentation](https://demergent-labs.github.io/kybra/).

diff --git a/docs/developer-docs/backend/typescript/index.mdx b/docs/developer-docs/backend/typescript/index.mdx
@@ -12,10 +12,22 @@ JavaScript is a well-known programming language used for web pages and other int
 
 TypeScript is a syntax built on top of JavaScript that enables types.
 
-To develop TypeScript and JavaScript smart contracts on ICP, the canister development kit (CDK)  known as [Azle](https://demergent-labs.github.io/azle/azle.html) can be used.
+To develop TypeScript and JavaScript smart contracts on ICP, the canister development kit (CDK) known as [Azle](https://demergent-labs.github.io/azle/azle.html) can be used.
 
 Azle is designed as a fully comprehensive TypeScript and JavaScript environment for ICP canisters. It supports as many relevant environment APIs as possible. These APIs are similar to those available in other frameworks such as Node.js and in environments such as web browsers.
 
+To use Azle, you must install the Azle `dfx` extension with the command:
+
+```
+npx azle install-dfx-extension
+```
+
+Then, you can create new Azle projects using the `npm azle new` command:
+
+```
+npx azle new my_project
+```
+
 Azle allows developers to bring their existing TypeScript and JavaScript skills and workflows to ICP, such as using npm packages and VS code intellisense.
 
 :::caution

diff --git a/docs/developer-docs/getting-started/default-template.mdx b/docs/developer-docs/getting-started/default-template.mdx
@@ -88,9 +88,14 @@ hello/
 ├── src                # Source files directory
 │   ├── hello_backend
 |   |   └── index.ts
-│   ├── hello_frontend
-│   │   ├── index.html
-│   │   └── index.ts
+│   ├── hello_frontend
+│       ├── assets
+│       │   ├── logo.png
+│       │   ├── main.css
+│       │   └── sample-asset.txt
+│       └── src
+│           ├── index.html
+│           └── index.js
 └── tsconfig.json
 ```
 
@@ -113,16 +118,12 @@ hello/
 │       │   ├── main.py
 │   ├── hello_frontend
 │       ├── assets
-|       |── index.html
-|       |── package.json
+│       │   ├── logo.png
+│       │   ├── main.css
+│       │   └── sample-asset.txt
 │       └── src
-│           ├── App.js
-│           ├── index.scss
-│           ├── logo2.svg
-│           ├── main.js
-│           └── vite-env.d.ts
-|       |── tsconfig.json
-|       |── vite.config.js
+│           ├── index.html
+│           └── index.js
 └── tsconfig.json
 ```
 
@@ -241,7 +242,20 @@ By default, the `dfx.json` file will contain automatically generated configurati
                 "node_compatibility": true
             }
         }
+        "hello_frontend": {
+          "dependencies": [
+            "hello_backend"
+          ],
+          "frontend": {
+            "entrypoint": "src/hello_frontend/src/index.html"
+          },
+          "source": [
+            "src/hello_frontend/assets",
+            "dist/hello_frontend/"
+          ],
+          "type": "assets"
     }
+  },
 }
 ```
 
@@ -252,23 +266,35 @@ By default, the `dfx.json` file will contain automatically generated configurati
 ```json title="dfx.json"
 {
   "canisters": {
-    "hello_backend": {
-      "build": "python -m kybra hello_backend src/hello_backend/src/main.py src/hello_backend/hello_backend.did",
-      "candid": "src/hello_backend/hello_backend.did",
-      "gzip": true,
-      "post_install": ".kybra/hello_backend/post_install.sh",
-      "type": "custom",
-      "wasm": ".kybra/hello_backend/hello_backend.wasm"
+      "hello_backend": {
+         "type": "custom",
+          "build": "python -m kybra hello_backend src/hello_backend/src/main.py src/hello_backend/hello_backend.did",
+          "candid": "src/hello_backend/hello_backend.did",
+          "gzip": true,
+          "wasm": ".kybra/hello_backend/hello_backend.wasm"
+              "metadata": [
+                  {
+                      "name": "candid:service",
+                      "path": "src/main.did"
+                  },
+                  {
+                      "name": "cdk:name",
+                      "content": "kybra"
+                  }
+              ],
     },
     "hello_frontend": {
       "dependencies": [
         "hello_backend"
       ],
-      "source": [
-        "src/hello_frontend/dist"
-      ],
-      "type": "assets",
-      "workspace": "hello_frontend"
+      "frontend": {
+        "entrypoint": "src/hello_frontend/src/index.html"
+          },
+          "source": [
+            "src/hello_frontend/assets",
+            "dist/hello_frontend/"
+          ],
+          "type": "assets"
     }
   },
   "defaults": {
@@ -282,7 +308,6 @@ By default, the `dfx.json` file will contain automatically generated configurati
 }
 ```
 
-
 </AdornedTab>
 </AdornedTabs>
 

diff --git a/docs/developer-docs/getting-started/hello-world.mdx b/docs/developer-docs/getting-started/hello-world.mdx
@@ -71,6 +71,10 @@ Download and install the latest version of [dfx](install/index.mdx). `dfx` is a
 sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
 ```
 
+:::info
+For Kybra projects, you will need to install `dfx` version `0.19.0` or newer, and you must run all `dfx` commands in a Python virtual environment.
+:::
+
 ### Install [Node.js](https://nodejs.org/en/download)
 
 ```bash
@@ -203,7 +207,7 @@ TypeScript canisters can be written using the Azle canister development kit. For
 npx azle install-dfx-extension
 ```
 
-The default canister code for Azle projects contains the following code:
+The default canister code for Azle projects contains the following:
 
 ```typescript title="src/hello_backend/src/index.ts"
 import { IDL, query, update } from 'azle';
@@ -227,7 +231,43 @@ export default class {
 
 <AdornedTab value={"python"} label="Python" endAdornment={<BetaChip />}>
 
-Create the project directory and file structure:
+Python canisters can be written using the Kybra canister development kit. 
+
+To set up a Python virtual environment, use the following commands:
+
+<Tabs>
+<TabItem value={"linux"} label="Linux">
+```
+curl https://pyenv.run | bash
+~/.pyenv/bin/pyenv install 3.10.7
+~/.pyenv/versions/3.10.7/bin/python -m venv venv
+source venv/bin/activate
+pip install kybra
+```
+</TabItem>
+
+<TabItem value={"macos"} label="macOS">
+```
+brew install pyenv
+export PYENV_ROOT="$HOME/.pyenv"
+[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init -)"
+source ~/.zprofile
+pyenv install 3.10.7
+~/.pyenv/versions/3.10.7/bin/python -m venv venv
+source venv/bin/activate
+pip install kybra
+```
+</TabItem>
+
+<TabItem value={"windows"} label="Windows">
+
+Refer to the [pyenv-win](https://github.com/pyenv-win/pyenv-win?tab=readme-ov-file) documentation for pyenv installation options on Windows.
+
+</TabItem>
+</Tabs>
+
+The default canister code for Kybra projects contains the following:
 
 ```python title="src/hello_backend/src/main.py"
 from kybra import query