docs: rework docs for v1 (#212)

BREAKING CHANGE: see 1.0 migration guide at https://algorand-devrel.github.io/beaker/html/migration.html

docs/html/_modules/index.html

@@ -45,8 +45,9 @@
 <li class="toctree-l1"><a class="reference internal" href="../sandbox.html">Sandbox</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../state.html">State</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../precompile.html">Precompile</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../decorators.html">Decorators</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../decorators.html">Decorator Parameters</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../testing.html">Testing</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../boxes.html">Boxes</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../migration.html">1.0 Migration Guide</a></li>
 </ul>
 
@@ -77,6 +78,8 @@ <h1>All modules for which code is available</h1>
 <ul><li><a href="beaker/application.html">beaker.application</a></li>
 <li><a href="beaker/client/application_client.html">beaker.client.application_client</a></li>
 <li><a href="beaker/decorators.html">beaker.decorators</a></li>
+<li><a href="beaker/lib/storage/box_list.html">beaker.lib.storage.box_list</a></li>
+<li><a href="beaker/lib/storage/box_mapping.html">beaker.lib.storage.box_mapping</a></li>
 <li><a href="beaker/logic_signature.html">beaker.logic_signature</a></li>
 <li><a href="beaker/precompile.html">beaker.precompile</a></li>
 <li><a href="beaker/sandbox/kmd.html">beaker.sandbox.kmd</a></li>

docs/html/_sources/application.rst.txt

@@ -1,13 +1,9 @@
 Application
 ============
 
-.. warning:: Out of date, needs to be updated to 1.0
-
 .. module:: beaker.application
 
-This is the base class that all Beaker Applications should inherit from.
-
-This class should **not** be initialized directly.
+This is the class that should be initialized for all Beaker Applications. 
 
 .. autoclass:: Application
     :members:

docs/html/_sources/application_client.rst.txt

@@ -1,42 +1,43 @@
 Application Client
 ===================
 
-.. warning:: Out of date, needs to be updated to 1.0
-
 .. currentmodule:: beaker.client
 
 
 .. _application_client:
 
 The ``ApplicationClient`` provides a convenient way to interact with our ``Application``.
 
+.. literalinclude:: ../../examples/client/main.py
+    :lines: 67-70
+
+By passing an ``AlgodClient``, an instance of our ``Application`` and a ``TransactionSigner``, we can easily make calls to our application. 
+
 .. note::
     The ``ApplicationClient`` takes an ``AlgodClient`` as its first argument, the most common API providers are available in ``beaker.client.api_providers``
 
-:ref:`Full Example <app_client_example>`
 
-The main point of interaction with our application is done using ``call``.  
+If the application does not yet exist, the ``app_id`` argument can be omitted but the first interaction with the ``Application`` should be to ``create`` it. Once this is done, the ``app_id`` will be set for the lifetime of the ``ApplicationClient`` instance.
+
+.. literalinclude:: ../../examples/client/main.py
+    :lines: 73-73 
+
+The primary way to of interact with our application is done using the ``call`` method, passing the method we want to call and the arguments it expects as keyword arguments.  
+
+.. literalinclude:: ../../examples/client/main.py
+    :lines: 80-80
 
-If there is an application already deployed, the ``app_id`` can be passed during initialization. If no ``app_id`` is passed, it's set to 0 so any app calls will be interpreted by the network as an intention to create the application. Once the ``create`` method is called the app id is set internally to the newly deployed application id and follow up calls will use that id.
 
 If there are multiple signers or you want to re-use some suggested parameters, the ``prepare`` method may be called with the different arguments and a copy of the client is returned with the updated parameters.
 
-.. autoclass:: ApplicationClient
+.. literalinclude:: ../../examples/client/main.py
+    :lines: 84-84
 
-    .. automethod:: call 
-    .. automethod:: add_method_call
-    .. automethod:: prepare
-    .. automethod:: create
-    .. automethod:: delete
-    .. automethod:: update 
-    .. automethod:: opt_in 
-    .. automethod:: close_out 
-    .. automethod:: clear_state 
-    .. automethod:: fund
-    .. automethod:: get_global_state
-    .. automethod:: get_application_account_info
-    .. automethod:: get_local_state
 
+:ref:`Full Example <app_client_example>`
+
+.. autoclass:: ApplicationClient
+    :members:
 
 .. _app_client_example:
 

docs/html/_sources/boxes.rst.txt

@@ -0,0 +1,47 @@
+.. _boxes:
+
+Boxes
+=====
+
+.. currentmodule:: beaker.lib.storage
+
+Applications that need to maintain a large amount of state can use ``Box`` data storage.
+
+:ref:`Full Example <box_example>`
+
+While ``PyTeal`` provides the basic tools for working with boxes, ``Beaker`` provides a few handy abstractions for working with them.
+
+.. _mapping:
+
+
+BoxMapping
+----------
+
+A ``BoxMapping`` provides a way to store data with a given key. 
+
+.. warning::
+    Care should be taken to ensure if multiple ``BoxMapping`` types are used, there is no overlap with keys. If there may be overlap, a ``prefix`` argument *MUST* be set in order to provide a unique namespace. 
+
+.. autoclass:: BoxMapping
+    :members:
+
+.. _listing:
+
+BoxList
+-------
+
+A ``BoxList`` provides a way to store some number of some _static_ abi type. 
+
+.. note::
+    Since the ``BoxList`` uses the size of the element to compute the offset into the box, the data type *MUST* be static.
+
+.. autoclass:: BoxList
+    :members:
+
+.. _box_example:
+
+Full Example
+------------
+
+.. literalinclude:: ../../examples/boxen/application.py
+

docs/html/_sources/decorators.rst.txt

@@ -1,33 +1,30 @@
-Decorators
-===========
+Decorator Parameters
+=====================
 
-.. warning:: Out of date, needs to be updated to 1.0
-
-Beaker uses decorated methods to apply configurations to the methods they decorate.  The configuration allows the ``Application`` class to know how to expose them.
+Beaker Application decorators accept parameters that apply configurations to the methods they decorate.
 
 
 .. module:: beaker.decorators
 
 .. _authorization:
 
 Authorization
-^^^^^^^^^^^^^
+-------------
 
 Often, we would like to restrict the accounts that may call certain methods. 
 
-.. autoclass:: Authorize
 
 
 Lets add a parameter to the external to allow only the app creator to call this method.
 
 .. code-block:: python
 
-    from beaker import Authorize
+    from beaker.decorators import Authorize
 
     #...
 
-    @external(authorize=Authorize.only(Global.creator_address()))
-    def increment(self, *, output: abi.Uint64):
+    @app.external(authorize=Authorize.only(Global.creator_address()))
+    def increment(*, output: abi.Uint64):
         return Seq(
             self.counter.set(self.counter + Int(1)),
             output.set(self.counter)
@@ -39,12 +36,12 @@ Now lets write a new method to allow any account that is opted in to call it:
 
 .. code-block:: python
     
-    from beaker import Authorize
+    from beaker.decorators import Authorize
 
     # ...
 
-    @external(authorize=Authorize.opted_in())
-    def vote(self, approve: abi.Bool):
+    @app.external(authorize=Authorize.opted_in())
+    def vote(approve: abi.Bool):
         # ...
 
 This authorize check will cause the contract call to fail if the sender has not opted in to the app. Another app id may also be passed in case you want to check if the Sender is opted in to a different application.
@@ -60,91 +57,57 @@ But we can define our own
 
 .. code-block:: python
 
+    from pyteal import Subroutine
     from beaker.consts import Algos
 
     @Subroutine(TealType.uint64)
     def is_whale(acct: Expr):
         # Only allow accounts with 1mm algos
         return Balance(acct)>Algos(1_000_000)
 
-    @external(authorize=is_whale)
+    # ...
+
+    @app.external(authorize=is_whale)
     def greet(*, output: abi.String):
         return output.set("hello whale")
 
-
-Application decorators
-----------------------
-
 .. _read_only:
 
-**Read Only**
+Read Only
+----------
 
 Methods that are meant to only produce information, having no side effects, should be flagged as read only. 
 
-See `ARC22 <https://github.com/algorandfoundation/ARCs/pull/79>`_ for more details.
+See `ARC22 <https://arc.algorand.foundation/ARCs/arc-0022>`_ for more details.
 
 .. code-block:: python
 
-    count = ApplicationStateValue(stack_type=TealType.uint64) 
+    class ROAppState:
+        count = ApplicationStateValue(stack_type=TealType.uint64) 
+
+    app = Application("CoolApp", state=ROAppState())
 
     @app.external(read_only=True)
-    def get_count(self, id_of_thing: abi.Uint8, *, output: abi.Uint64):
-        return output.set(self.count)
+    def get_count(id_of_thing: abi.Uint8, *, output: abi.Uint64):
+        return output.set(app.state.count)
 
 
-.. _internal_methods:
+.. _oncomplete_settings:
 
-Subroutines
+On Complete
 -----------
 
-An Application will often need a number of internal ``utility`` type methods to handle common logic.  
-We don't want to expose these methods to the ABI but we do want to allow them to access any instance variables.
-
-.. note:: 
-    If you want some method to return the expression only and not be triggered with ``callsub``, omit the ``@Subroutine`` decorator and the expression will be inlined
-
-.. code-block:: python
-
-    @pyteal.Subroutine(TealType.uint64)
-    def do_logic(self):
-        return If(self.counter>10, self.send_asset())
+If a method expects the ``ApplicationCallTransaction`` to have a certain  ``OnComplete`` other than ``NoOp``, one of the other ``OnComplete`` decorators may be used instead of ``external`` with a method config set.
 
 .. module:: beaker.application
-    :noindex:
-
-.. _external:
-
-ABI Method external
---------------------
-
-The ``external`` decorator is how we can add methods to be handled as ABI methods.
-
-Tagging a method as ``external`` adds it to the internal ``Router`` with whatever configuration is passed, if any.
-
-.. autoclass:: Application
-    :noindex:
-    :special-members:
-    :members: external
-
-.. _oncomplete_externals:
-
-OnComplete Externals 
----------------------
-
-If a method expects the ``ApplicationCallTransaction`` to have an  ``OnComplete`` other than ``NoOp``, one of the other ``OnComplete`` decorators may be used instead of ``external`` with a method config set.
-
-
-OnComplete Decorators 
-^^^^^^^^^^^^^^^^^^^^^
-
 .. autoclass:: Application
     :noindex:
     :special-members:
     :members: external, create, delete, update, opt_in, close_out, clear_state
 
-The ARC4 spec allows applications to define externals for ``bare`` methods, that is methods with no application arguments. 
+The `ARC4 <https://arc.algorand.foundation/ARCs/arc-0022>`_ spec allows applications to define externals for ``bare`` methods, that is, methods with no application arguments. 
 
-Routing for ``bare`` methods is based on the transaction's ``OnComplete`` and whether or not it's a Create transaction.
+Routing for ``bare`` methods is based on the transaction's ``OnComplete`` and whether or not it's a create transaction, not based on the method selector as non-bare methods.
 
 The same handlers described above will also work for ``bare`` method calls but multiple ``OnComplete`` values can be handled with the ``bare_external`` decorator.
 

docs/html/_sources/index.rst.txt

@@ -63,6 +63,7 @@ See full examples `here <https://github.com/algorand-devrel/beaker/tree/master/e
     precompile
     decorators
     testing
+    boxes
     migration
 
 

docs/html/_sources/lsig.rst.txt

@@ -1,22 +1,31 @@
 Logic Signatures
 ================
 
-.. warning:: Out of date, needs to be updated to 1.0
-
 .. module:: beaker.logic_signature
 
-This is the base class that all Beaker LogicSignatures should inherit from.
+This is the class that should be initialized to provide a LogicSignature.
+
+A ``LogicSignature`` is intialized with either a PyTeal ``Expr`` or a function that returns an ``Expr``.
+
+.. literalinclude:: ../../examples/offload_compute/lsig.py
+    :lines: 30-52
+
+A ``LogicSignatureTemplate`` is initialized by passing a PyTeal ``Expr`` or a function that returns an ``Expr`` _and_ a dictionary of template variables that should be provided at runtime.
 
-This class should **not** be initialized directly.
 
-:ref:`Full Example <lsig_example>`
+.. literalinclude:: ../../examples/templated_lsig/main.py
+    :lines: 29-45
+
 
 .. autoclass:: LogicSignature
     :members:
 
 .. autoclass:: LogicSignatureTemplate
     :members:
 
+.. autoclass:: RuntimeTemplateVariable
+    :members:
+
 .. _lsig_example:
 
 Logic Signature Example