Cyfrin · PatrickAlphaC · Sep 20, 2024 · Sep 20, 2024
diff --git a/README.md b/README.md
@@ -59,4 +59,16 @@ The documentation roughly attempts to follow [Diátaxis](https://diataxis.fr/).
 
 ## Background
 
-> Agkistrodon piscivorus is a species of venomous snake, a pit viper in the subfamily Crotalinae of the family Viperidae. The generic name is derived from the Greek words ἄγκιστρον agkistron "fish-hook, hook" and ὀδών odon "tooth", and the specific name comes from the Latin piscis 'fish' and voro '(I) eat greedily, devour'; thus, the scientific name translates to "hook-toothed fish-eater". Common names include cottonmouth, northern cottonmouth, water moccasin, swamp moccasin, black moccasin, and simply viper.
+> Agkistrodon piscivorus is a species of venomous snake, a pit viper in the subfamily Crotalinae of the family Viperidae. The generic name is derived from the Greek words ἄγκιστρον agkistron "fish-hook, hook" and ὀδών odon "tooth", and the specific name comes from the Latin piscis 'fish' and voro '(I) eat greedily, devour'; thus, the scientific name translates to "hook-toothed fish-eater". Common names include cottonmouth, northern cottonmouth, water moccasin, swamp moccasin, black moccasin, and simply viper.
+
+
+# License 
+
+moccasin is licensed under either of:
+
+- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
+- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
+
+at your option.
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in moccasin by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any additional terms or conditions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -25,6 +25,7 @@
     "sphinx_copybutton",
     "sphinx_multiversion",
     "sphinxarg.ext",
+    "sphinx_tabs.tabs",
 ]
 
 master_doc = "toctree"

diff --git a/docs/source/dependencies.rst b/docs/source/dependencies.rst
@@ -1,7 +1,6 @@
 Dependencies 
 ############
 
-
 Moccasin allows for working with either:
 
 - :ref:`Installing from GitHub repositories <installing_github_dependencies>`

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -44,6 +44,34 @@ How to read the documentation
 
 The moccasin documentation is written in a way that assumes you are on a MacOS or Linux-like system. If you are using windows, we recommend you watch the first `10 minutes of this WSL tutorial <https://www.youtube.com/watch?v=xqUZ4JqHI_8>`_ and work with WSL. WSL stands for "Windows Subsystem for Linux" and it allows you to run a Linux commands on Windows machine.
 
+
+TOML Formatting
+---------------
+
+In TOML you can think of each section as a giant JSON object. Each of these are essentially identical:
+
++----------------------------------+----------------------------------+----------------------------------+
+| TOML (Expanded)                  | TOML (Compact)                   | JSON                             |
++==================================+==================================+==================================+
+| .. code-block:: toml             | .. code-block:: bash             | .. code-block:: json             |
+|                                  |                                  |                                  |
+|    [project]                     |    [project]                     |    {                             |
+|    src = "contracts"             |    src = "contracts"             |      "project": {                |
+|                                  |    networks = {                  |        "src": "contracts",       |
+|    [project.networks.sepolia]    |      sepolia = {                 |        "networks": {             |
+|    url = "https://..."           |        url = "https://...",      |          "sepolia": {            |
+|    chain_id = 11155111           |        chain_id = 11155111       |            "url": "https://...", |
+|                                  |      },                          |            "chain_id": 11155111  |
+|    [project.networks.zksync]     |      zksync = {                  |          },                      |
+|    url = "https://..."           |        url = "https://...",      |          "zksync": {             |
+|    chain_id = 324                |        chain_id = 324            |            "url": "https://...", |
+|                                  |      }                           |            "chain_id": 324       |
+|                                  |    }                             |          }                       |
+|                                  |                                  |        }                         |
+|                                  |                                  |      }                           |
+|                                  |                                  |    }                             |
++----------------------------------+----------------------------------+----------------------------------+
+
 Why Moccasin?
 =============
 

diff --git a/docs/source/installing-moccasin.rst b/docs/source/installing-moccasin.rst
@@ -1,58 +1,122 @@
 .. _install: 
 
+###################
 Installing Moccasin
 ###################
 
+.. note:: Beginner Developers:
+
+    Are you a new or beginner python developer? Then follow these steps:
+
+    1. :ref:`Install uv <installation-with-uv>`
+
+    2. :ref:`In an isolated environment <isolated_uv>`
+
+    3. :ref:`Check to see if it worked <after_install>`
+
+    4. :doc:`Go to the quickstart! <quickstart>`
+
 There are a few things you'll need on your machine before you can install Moccasin. Please install the appropriate tools from the `Prerequisites`_ section. Once you have those, the recommended way to :ref:`install Moccasin is via uv <installation-with-uv>`.
 
+.. contents::
+   :depth: 3
+   :local:
+
+
 Prerequisites
-=============
+#############
 
 1. Python 3.11 or later
 
 .. _installation-with-uv:
 
 Installation with uv
---------------------
+====================
 
-For those unfamiliar, `uv <https://docs.astral.sh/uv/>`_ is a fast python package manager, and that helps us install moccasin into it's own isolated virtual environment, so we don't get any weird dependency conflicts with other python packages. It's similar to `pip` and `pipx` if you've used them before. It even comes with some `pip` compatibility, will tools like `uv pip install`.
+For those unfamiliar, `uv <https://docs.astral.sh/uv/>`_ is a fast python package manager that helps us install moccasin into it's own isolated virtual environment, so we don't get any weird dependency conflicts with other python packages. It's similar to `pip` and `pipx` if you've used them before. It even comes with some `pip` compatibility, will tools like `uv pip install`.
 
 It's highly recommended you understand how `virtual environments <https://docs.python.org/3/library/venv.html>`_ work as well. 
 
-The easiest way to install `uv` is:
+The easiest way to install ``uv`` is:
 
-.. code-block:: bash
+.. tabs::
+
+    .. code-tab:: bash linux / MacOS
+
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+
+    .. tab:: Windows
+
+        ``powershell -c "irm https://astral.sh/uv/install.ps1 | iex"``
+
+        .. note:: 
 
-    curl -LsSf https://astral.sh/uv/install.sh | sh
+            ⚠️ Windows users: We recommend you watch the first `10 minutes of this WSL tutorial <https://www.youtube.com/watch?v=xqUZ4JqHI_8>`_ and install and work with WSL. WSL stands for "Windows Subsystem for Linux" and it allows you to run a Linux commands on Windows machine. If you're working on WSL, you can just use the ``linux / MacOS`` command from the other tab.
 
 But you can head over to the `uv installation instructions <https://docs.astral.sh/uv/getting-started/installation/>`_ for more options. If you don't have at least Python 3.11 installed, you'll need to install that first.
 
 .. code-block:: bash
 
     uv python install 3.11
 
+.. _isolated_uv:
+
+Isolated Environment
+--------------------
+
+To install ``moccasin`` into an isolated environment, you can run:
+
 Then, to install moccasin with `uv`, run:
 
 .. code-block:: bash
 
     uv tool install moccasin
 
-Once installed, to verify that Moccasin is installed, you can run:
+If you wish to install ``moccasin`` and use other python packages in your scripts, you'll use the ``with`` flag:
 
 .. code-block:: bash
 
-    mox --version
+    uv tool install moccasin --with pandas
 
-And see an output like:
+.. note::
+
+    Installing ``moccasin`` into a virtual environment (via ``uv tools install`` or ``pipx install``) will require a different setup for injecting python packages. See :doc:`virtual_environments` for more information.
+
+Then, go to :ref:`after installation <after_install>`.
+
+
+Virtual Environment
+-------------------
+
+If instead, you'd prefer to have different ``mox`` executeables Or, if you want to have ``moccasin`` installed with a traditional virtual environment set, you can run:
+
+.. code-block:: bash
+
+    uv init
+    uv venv
+    source .venv/bin/activate
+
+Then, you can install it as a uv installation:
+
+.. code-block:: bash
+
+    uv add moccasin
+
+Where you'll be able to run the executeable with ``uv run mox`` instead of ``mox`` (see :ref:`after installation <after_install>`).
+
+Or a pip installation:
 
 .. code-block:: bash
 
-    Moccasin CLI v0.1.0
+    uv pip install moccasin
+
+Where you'll be able to run the executeable with ``mox`` (see :ref:`after installation <after_install>`).
+
 
 .. _installation-with-pipx:
 
 Installation with pipx
-----------------------
+======================
 
 Pipx is a tool to help you install and run end-user applications written in Python. It's roughly similar to macOS's ``brew``, JavaScript's ``npx``, and Linux's ``apt``.
 
@@ -79,31 +143,28 @@ To install moccasin then with `pipx`:
 
     pipx install moccasin
 
-Once installed, you can run the following command to verify that Moccasin is installed:
-
-.. code-block:: bash
-
-    mox --version
 
-And see an output like:
+.. note::
 
-.. code-block:: bash
+    Installing ``moccasin`` into a virtual environment (via ``uv tools install`` or ``pipx install``) will require a different setup for injecting python packages. See :doc:`virtual_environments` for more information.
 
-    Moccasin CLI v0.1.0
+Then, go to :ref:`after installation <after_install>`.
 
 Installation with pip
----------------------
+=====================
 
-You can install with `pip`, and if you do so, it's highly recommended you understand how `virtual environments <https://docs.python.org/3/library/venv.html>`_ work. 
+You can install with ``pip``, and if you do so, it's highly recommended you understand how `virtual environments <https://docs.python.org/3/library/venv.html>`_ work. 
 
 To install with `pip`:
 
 .. code-block:: bash
 
     pip install moccasin
+
+Then, go to :ref:`after installation <after_install>`.
 
 From source 
------------
+===========
 
 To install from source, you'll need the `uv tool installed <https://docs.astral.sh/uv/>`_. Once installed, you can run:
 
@@ -115,4 +176,24 @@ To install from source, you'll need the `uv tool installed <https://docs.astral.
     source .venv/bin/activate
     uv pip install -e .
 
-And you will have `mox` in your virtual environment created from the `uv` tool. It's highly recommended you understand how `virtual environments <https://docs.python.org/3/library/venv.html>`_ work. 
+And you will have ``mox`` in your virtual environment created from the ``uv`` tool. It's highly recommended you understand how `virtual environments <https://docs.python.org/3/library/venv.html>`_ work. 
+
+
+Then, go to :ref:`after installation <after_install>`.
+
+.. _after_install:
+
+After installation
+##################
+
+Once installed, to verify that Moccasin is installed, you can run:
+
+.. code-block:: bash
+
+    mox --version
+
+And see an output like:
+
+.. code-block:: bash
+
+    Moccasin CLI v0.1.0
diff --git a/docs/source/named_contracts.rst b/docs/source/named_contracts.rst
@@ -60,17 +60,31 @@ Now, just getting the address is pretty boring, typically you want to interact w
 
 There are a number of flags we can set for our ``NamedContract``:
 
-.. code-block:: toml
+.. tabs:: 
+
+    .. code-tab:: toml true-toml
 
-    [networks.mainnet-fork.contracts]
-    usdc = { 
+        [networks.mainnet-fork.contracts.usdc]
         address = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
         abi = "ERC20.vy"
         abi_from_explorer = true
         fixture = false
         deployment_script = "script/deploy_erc20.py"
         force_deploy = false
-    }
+
+    .. code-tab:: bash ugly-toml
+
+        # Did you know that this format will work the same?
+        # It's technically the "uglier" version toml 
+        [networks.mainnet-fork.contracts]
+        usdc = {
+            address = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+            abi = "ERC20.vy"
+            abi_from_explorer = true
+            fixture = false
+            deployment_script = "script/deploy_erc20.py"
+            force_deploy = false
+        }
 
 Let's break these down:
 

diff --git a/docs/source/pyevm.rst b/docs/source/pyevm.rst
@@ -5,7 +5,7 @@ If you don't specify a network in your command line, by default, ``moccasin`` wi
 
 This is a built-in network that comes with `titanoboa <https://titanoboa.readthedocs.io/en/latest/overview.html>`_, and can be considered the core engine of the whole ``moccasin`` project.
 
-So, when you originally :doc:`mox init <quickstart.rst>` a project, you get a deploy script that looks like this:
+So, when you originally :doc:`mox init <quickstart>` a project, you get a deploy script that looks like this:
 
 .. code-block:: python 
 

diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -137,40 +137,8 @@ You'll get an output like:
     ==================================== 1 passed in 0.01s ====================================
 
 
-Adding python dependencies  
-==========================
-
 .. note:: 
 
-    You can see more about python dependencies in the :doc:`virtual environments documentation <virtual_environments>`.
-
-    Ideally, you'll use a virtual environment to manage your python dependencies so they don't get tangled up! That is also in our :doc:`virtual environments documentation <virtual_environments>`
-
-To add a python package, you can install it to your environment or virtual environment like normal:
-
-.. code-block:: bash 
-
-    # The "normal" python way
-    pip install pandas 
-
-    # Our recommended appraoch
-    uv add pandas 
-
-Then, just import the package
-
-.. code-block:: python
-
-    from src import Counter
-    import pandas # HERE!
-
-    def deploy():
-        counter = Counter.deploy()
-        print("Starting count: ", counter.number())
-        counter.increment()
-        print("Ending count: ", counter.number())
-        return counter
-
-    def moccasin_main():
-        return deploy()
+    If you want to add python dependencies to your ``moccasin`` project, see: :doc:`virtual environments documentation <virtual_environments>`.
 
-And you can use the package in the script!
+But that's it! You've now successfully gotten your first package up and going!
diff --git a/docs/source/toctree.rst b/docs/source/toctree.rst
@@ -46,7 +46,7 @@ Moccasin
 ..     :caption: Tutorials
 ..     :maxdepth: 3
 
-..     .. TODO 
+..     new_dev_tutorial.rst
 
 .. toctree::
     :caption: Class, Config, and other Reference