Merge pull request #497 from demergent-labs/update_documentation

Update documentation

docs/deployment.html

@@ -247,10 +247,27 @@ <h2 id="deploying-to-mainnet"><a class="header" href="#deploying-to-mainnet">Dep
 <h2 id="common-deployment-issues"><a class="header" href="#common-deployment-issues">Common deployment issues</a></h2>
 <p>If you run into an error during deployment, try the following:</p>
 <ol>
-<li>Ensure that you have followed the instructions correctly in <a href="./installation.html">the installation chapter</a>, especially noting <a href="./installation.html#common-installation-issues">the common installation issues</a></li>
-<li>Look for more error output by adding the <code>--verbose</code> flag to the <code>build</code> command in your <code>dfx.json</code> file like so: <code>&quot;build&quot;: &quot;python -m kybra canister_name src/main.py src/main.did --verbose</code></li>
-<li>Look for errors in each of the files in <code>~/.config/kybra/[kybra_version]/logs</code></li>
-<li>If the problem is still not resolved, reach out with any error outputs in <a href="https://discord.gg/ux2Jc7psjd">the Discord channel</a></li>
+<li>
+<p>Ensure that you have followed the instructions correctly in <a href="./installation.html">the installation chapter</a>, especially noting <a href="./installation.html#common-installation-issues">the common installation issues</a></p>
+</li>
+<li>
+<p>Ensure that you have created and activated your virtual environment, and that you have done the following from within that virtual environment: installed Kybra, installed the Kybra dfx extension, and run <code>dfx deploy</code>:</p>
+<pre><code class="language-bash">~/.pyenv/versions/3.10.7/bin/python -m venv venv
+source venv/bin/activate
+pip install kybra
+python -m kybra install-dfx-extension
+dfx deploy
+</code></pre>
+</li>
+<li>
+<p>Look for more error output by adding the <code>KYBRA_VERBOSE=true</code> environment variable to <code>dfx deploy</code> like so: <code>KYBRA_VERBOSE=true dfx deploy</code></p>
+</li>
+<li>
+<p>Look for errors in each of the files in <code>~/.config/kybra/[kybra_version]/logs</code></p>
+</li>
+<li>
+<p>If the problem is still not resolved, reach out with any error outputs in <a href="https://discord.gg/ux2Jc7psjd">the Discord channel</a></p>
+</li>
 </ol>
 
                     </main>

docs/hello_world.html

@@ -170,8 +170,9 @@ <h2 id="the-project-directory-and-file-structure"><a class="header" href="#the-p
 <pre><code class="language-bash">~/.pyenv/versions/3.10.7/bin/python -m venv venv
 source venv/bin/activate
 </code></pre>
-<p>Now install Kybra:</p>
+<p>Now install Kybra and the Kybra dfx extension:</p>
 <pre><code class="language-bash">pip install kybra
+python -m kybra install-dfx-extension
 </code></pre>
 <p>Open up <code>kybra_hello_world</code> in your text editor (we recommend <a href="https://code.visualstudio.com/">VS Code</a> with the <a href="https://marketplace.visualstudio.com/items?itemName=ms-python.python">Microsoft Python extension</a>).</p>
 <h2 id="mainpy"><a class="header" href="#mainpy">main.py</a></h2>
@@ -222,21 +223,8 @@ <h2 id="dfxjson"><a class="header" href="#dfxjson">dfx.json</a></h2>
 <pre><code class="language-json">{
     &quot;canisters&quot;: {
         &quot;kybra_hello_world&quot;: {
-            &quot;type&quot;: &quot;custom&quot;,
-            &quot;build&quot;: &quot;python -m kybra kybra_hello_world src/main.py src/main.did&quot;,
-            &quot;candid&quot;: &quot;src/main.did&quot;,
-            &quot;wasm&quot;: &quot;.kybra/kybra_hello_world/kybra_hello_world.wasm&quot;,
-            &quot;gzip&quot;: true,
-            &quot;metadata&quot;: [
-                {
-                    &quot;name&quot;: &quot;candid:service&quot;,
-                    &quot;path&quot;: &quot;src/main.did&quot;
-                },
-                {
-                    &quot;name&quot;: &quot;cdk:name&quot;,
-                    &quot;content&quot;: &quot;kybra&quot;
-                }
-            ]
+            &quot;type&quot;: &quot;kybra&quot;,
+            &quot;main&quot;: &quot;src/main.py&quot;
         }
     }
 }

docs/installation.html

@@ -154,7 +154,7 @@ <h2 id="dependencies"><a class="header" href="#dependencies">Dependencies</a></h
 <p>You should be using a *nix environment (Linux, Mac OS, <a href="https://learn.microsoft.com/en-us/windows/wsl/install">WSL if using Windows</a>) with bash and have the following installed on your system:</p>
 <ul>
 <li>Python 3.10.7</li>
-<li>dfx 0.19.0</li>
+<li>dfx 0.23.0</li>
 <li>Python VS Code Extension</li>
 </ul>
 <h3 id="python-3107"><a class="header" href="#python-3107">Python 3.10.7</a></h3>
@@ -166,8 +166,8 @@ <h3 id="python-3107"><a class="header" href="#python-3107">Python 3.10.7</a></h3
 ~/.pyenv/bin/pyenv install 3.10.7
 </code></pre>
 <h3 id="dfx"><a class="header" href="#dfx">dfx</a></h3>
-<p>Run the following command to install dfx 0.19.0:</p>
-<pre><code class="language-bash">DFX_VERSION=0.19.0 sh -ci &quot;$(curl -fsSL https://sdk.dfinity.org/install.sh)&quot;
+<p>Run the following command to install dfx 0.23.0:</p>
+<pre><code class="language-bash">DFX_VERSION=0.23.0 sh -ci &quot;$(curl -fsSL https://sdk.dfinity.org/install.sh)&quot;
 </code></pre>
 <p>If after trying to run <code>dfx</code> commands you encounter an error such as <code>dfx: command not found</code>, you might need to add <code>$HOME/bin</code> to your path. Here's an example of doing this in your <code>.bashrc</code>:</p>
 <pre><code class="language-bash">echo 'export PATH=&quot;$PATH:$HOME/bin&quot;' &gt;&gt; &quot;$HOME/.bashrc&quot;

docs/kybra.html

@@ -160,7 +160,7 @@ <h2 id="disclaimer"><a class="header" href="#disclaimer">Disclaimer</a></h2>
 <li>Kybra uses a new Python interpreter that is less mature than CPython</li>
 </ul>
 <h2 id="roadmap"><a class="header" href="#roadmap">Roadmap</a></h2>
-<p>We hope to get to a production-ready 1.0 in 2024. The following are the major blockers to 1.0:</p>
+<p>We hope to get to a production-ready 1.0 in 2025. The following are the major blockers to 1.0:</p>
 <ul>
 <li>CPython integration for performance, security, and stability</li>
 <li>Broad PyPI package support (C API/extensions)</li>

docs/print.html

@@ -194,7 +194,7 @@ <h2 id="disclaimer"><a class="header" href="#disclaimer">Disclaimer</a></h2>
 <li>Kybra uses a new Python interpreter that is less mature than CPython</li>
 </ul>
 <h2 id="roadmap"><a class="header" href="#roadmap">Roadmap</a></h2>
-<p>We hope to get to a production-ready 1.0 in 2024. The following are the major blockers to 1.0:</p>
+<p>We hope to get to a production-ready 1.0 in 2025. The following are the major blockers to 1.0:</p>
 <ul>
 <li>CPython integration for performance, security, and stability</li>
 <li>Broad PyPI package support (C API/extensions)</li>
@@ -342,7 +342,7 @@ <h2 id="dependencies"><a class="header" href="#dependencies">Dependencies</a></h
 <p>You should be using a *nix environment (Linux, Mac OS, <a href="https://learn.microsoft.com/en-us/windows/wsl/install">WSL if using Windows</a>) with bash and have the following installed on your system:</p>
 <ul>
 <li>Python 3.10.7</li>
-<li>dfx 0.19.0</li>
+<li>dfx 0.23.0</li>
 <li>Python VS Code Extension</li>
 </ul>
 <h3 id="python-3107"><a class="header" href="#python-3107">Python 3.10.7</a></h3>
@@ -354,8 +354,8 @@ <h3 id="python-3107"><a class="header" href="#python-3107">Python 3.10.7</a></h3
 ~/.pyenv/bin/pyenv install 3.10.7
 </code></pre>
 <h3 id="dfx"><a class="header" href="#dfx">dfx</a></h3>
-<p>Run the following command to install dfx 0.19.0:</p>
-<pre><code class="language-bash">DFX_VERSION=0.19.0 sh -ci &quot;$(curl -fsSL https://sdk.dfinity.org/install.sh)&quot;
+<p>Run the following command to install dfx 0.23.0:</p>
+<pre><code class="language-bash">DFX_VERSION=0.23.0 sh -ci &quot;$(curl -fsSL https://sdk.dfinity.org/install.sh)&quot;
 </code></pre>
 <p>If after trying to run <code>dfx</code> commands you encounter an error such as <code>dfx: command not found</code>, you might need to add <code>$HOME/bin</code> to your path. Here's an example of doing this in your <code>.bashrc</code>:</p>
 <pre><code class="language-bash">echo 'export PATH=&quot;$PATH:$HOME/bin&quot;' &gt;&gt; &quot;$HOME/.bashrc&quot;
@@ -416,8 +416,9 @@ <h2 id="the-project-directory-and-file-structure"><a class="header" href="#the-p
 <pre><code class="language-bash">~/.pyenv/versions/3.10.7/bin/python -m venv venv
 source venv/bin/activate
 </code></pre>
-<p>Now install Kybra:</p>
+<p>Now install Kybra and the Kybra dfx extension:</p>
 <pre><code class="language-bash">pip install kybra
+python -m kybra install-dfx-extension
 </code></pre>
 <p>Open up <code>kybra_hello_world</code> in your text editor (we recommend <a href="https://code.visualstudio.com/">VS Code</a> with the <a href="https://marketplace.visualstudio.com/items?itemName=ms-python.python">Microsoft Python extension</a>).</p>
 <h2 id="mainpy"><a class="header" href="#mainpy">main.py</a></h2>
@@ -468,21 +469,8 @@ <h2 id="dfxjson"><a class="header" href="#dfxjson">dfx.json</a></h2>
 <pre><code class="language-json">{
     &quot;canisters&quot;: {
         &quot;kybra_hello_world&quot;: {
-            &quot;type&quot;: &quot;custom&quot;,
-            &quot;build&quot;: &quot;python -m kybra kybra_hello_world src/main.py src/main.did&quot;,
-            &quot;candid&quot;: &quot;src/main.did&quot;,
-            &quot;wasm&quot;: &quot;.kybra/kybra_hello_world/kybra_hello_world.wasm&quot;,
-            &quot;gzip&quot;: true,
-            &quot;metadata&quot;: [
-                {
-                    &quot;name&quot;: &quot;candid:service&quot;,
-                    &quot;path&quot;: &quot;src/main.did&quot;
-                },
-                {
-                    &quot;name&quot;: &quot;cdk:name&quot;,
-                    &quot;content&quot;: &quot;kybra&quot;
-                }
-            ]
+            &quot;type&quot;: &quot;kybra&quot;,
+            &quot;main&quot;: &quot;src/main.py&quot;
         }
     }
 }
@@ -622,10 +610,27 @@ <h2 id="deploying-to-mainnet"><a class="header" href="#deploying-to-mainnet">Dep
 <h2 id="common-deployment-issues"><a class="header" href="#common-deployment-issues">Common deployment issues</a></h2>
 <p>If you run into an error during deployment, try the following:</p>
 <ol>
-<li>Ensure that you have followed the instructions correctly in <a href="./installation.html">the installation chapter</a>, especially noting <a href="./installation.html#common-installation-issues">the common installation issues</a></li>
-<li>Look for more error output by adding the <code>--verbose</code> flag to the <code>build</code> command in your <code>dfx.json</code> file like so: <code>&quot;build&quot;: &quot;python -m kybra canister_name src/main.py src/main.did --verbose</code></li>
-<li>Look for errors in each of the files in <code>~/.config/kybra/[kybra_version]/logs</code></li>
-<li>If the problem is still not resolved, reach out with any error outputs in <a href="https://discord.gg/ux2Jc7psjd">the Discord channel</a></li>
+<li>
+<p>Ensure that you have followed the instructions correctly in <a href="./installation.html">the installation chapter</a>, especially noting <a href="./installation.html#common-installation-issues">the common installation issues</a></p>
+</li>
+<li>
+<p>Ensure that you have created and activated your virtual environment, and that you have done the following from within that virtual environment: installed Kybra, installed the Kybra dfx extension, and run <code>dfx deploy</code>:</p>
+<pre><code class="language-bash">~/.pyenv/versions/3.10.7/bin/python -m venv venv
+source venv/bin/activate
+pip install kybra
+python -m kybra install-dfx-extension
+dfx deploy
+</code></pre>
+</li>
+<li>
+<p>Look for more error output by adding the <code>KYBRA_VERBOSE=true</code> environment variable to <code>dfx deploy</code> like so: <code>KYBRA_VERBOSE=true dfx deploy</code></p>
+</li>
+<li>
+<p>Look for errors in each of the files in <code>~/.config/kybra/[kybra_version]/logs</code></p>
+</li>
+<li>
+<p>If the problem is still not resolved, reach out with any error outputs in <a href="https://discord.gg/ux2Jc7psjd">the Discord channel</a></p>
+</li>
 </ol>
 <div style="break-before: page; page-break-before: always;"></div><h1 id="examples"><a class="header" href="#examples">Examples</a></h1>
 <p>Kybra has many example projects showing nearly all Kybra APIs. They can be found in the <a href="https://github.com/demergent-labs/kybra/tree/main/examples">examples directory</a> of the <a href="https://github.com/demergent-labs/kybra">Kybra GitHub repository</a>.</p>

the_kybra_book/src/deployment.md

@@ -160,6 +160,16 @@ If you have problems deploying see [Common deployment issues](./deployment.md#co
 If you run into an error during deployment, try the following:
 
 1. Ensure that you have followed the instructions correctly in [the installation chapter](./installation.md), especially noting [the common installation issues](./installation.md#common-installation-issues)
-2. Look for more error output by adding the `--verbose` flag to the `build` command in your `dfx.json` file like so: `"build": "python -m kybra canister_name src/main.py src/main.did --verbose`
-3. Look for errors in each of the files in `~/.config/kybra/[kybra_version]/logs`
-4. If the problem is still not resolved, reach out with any error outputs in [the Discord channel](https://discord.gg/ux2Jc7psjd)
+2. Ensure that you have created and activated your virtual environment, and that you have done the following from within that virtual environment: installed Kybra, installed the Kybra dfx extension, and run `dfx deploy`:
+
+    ```bash
+    ~/.pyenv/versions/3.10.7/bin/python -m venv venv
+    source venv/bin/activate
+    pip install kybra
+    python -m kybra install-dfx-extension
+    dfx deploy
+    ```
+
+3. Look for more error output by adding the `KYBRA_VERBOSE=true` environment variable to `dfx deploy` like so: `KYBRA_VERBOSE=true dfx deploy`
+4. Look for errors in each of the files in `~/.config/kybra/[kybra_version]/logs`
+5. If the problem is still not resolved, reach out with any error outputs in [the Discord channel](https://discord.gg/ux2Jc7psjd)

the_kybra_book/src/hello_world.md

@@ -34,10 +34,11 @@ Now create and source a virtual environment:
 source venv/bin/activate
 ```
 
-Now install Kybra:
+Now install Kybra and the Kybra dfx extension:
 
 ```bash
 pip install kybra
+python -m kybra install-dfx-extension
 ```
 
 Open up `kybra_hello_world` in your text editor (we recommend [VS Code](https://code.visualstudio.com/) with the [Microsoft Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)).
@@ -112,21 +113,8 @@ Create the following in `kybra_hello_world/dfx.json`:
 {
     "canisters": {
         "kybra_hello_world": {
-            "type": "custom",
-            "build": "python -m kybra kybra_hello_world src/main.py src/main.did",
-            "candid": "src/main.did",
-            "wasm": ".kybra/kybra_hello_world/kybra_hello_world.wasm",
-            "gzip": true,
-            "metadata": [
-                {
-                    "name": "candid:service",
-                    "path": "src/main.did"
-                },
-                {
-                    "name": "cdk:name",
-                    "content": "kybra"
-                }
-            ]
+            "type": "kybra",
+            "main": "src/main.py"
         }
     }
 }

the_kybra_book/src/kybra.md

@@ -17,7 +17,7 @@ Kybra may have unknown security vulnerabilities due to the following:
 
 ## Roadmap
 
-We hope to get to a production-ready 1.0 in 2024. The following are the major blockers to 1.0:
+We hope to get to a production-ready 1.0 in 2025. The following are the major blockers to 1.0:
 
 -   CPython integration for performance, security, and stability
 -   Broad PyPI package support (C API/extensions)