Move 'building chains' into cookbooks

Author: cburgdorf

docs/cookbooks/index.rst

@@ -0,0 +1,53 @@
+Cookbooks
+=========
+
+The Cookbooks are collections of simple recipes that demonstrate good practices to accomplish
+common tasks. The examples are usually short answers to simple "How do I..." questions that go
+beyond simple API descriptions but also don't need a full guide to become clear.
+
+.. _evm_cookbook:
+
+EVM Cookbook
+~~~~~~~~~~~~
+
+.. _evm_cookbook_recipe_using_the_chain_object:
+
+Using the Chain object
+----------------------
+
+A "single" blockchain is made by a series of different virtual machines
+for different spans of blocks. For example, the Ethereum mainnet had
+one virtual machine for blocks 0 till 1150000 (known as Frontier),
+and another VM for blocks 1150000 till 1920000 (known as Homestead).
+
+The :class:`~eth.chains.chain.Chain` object manages the series of fork rules,
+after you define the VM ranges. For example, to set up a chain that would track
+the mainnet Ethereum network until block 1920000, you could create this chain
+class:
+
+.. doctest::
+
+  >>> from eth import constants, Chain
+  >>> from eth.vm.forks.frontier import FrontierVM
+  >>> from eth.vm.forks.homestead import HomesteadVM
+  >>> from eth.chains.mainnet import HOMESTEAD_MAINNET_BLOCK
+
+  >>> chain_class = Chain.configure(
+  ...     __name__='Test Chain',
+  ...     vm_configuration=(
+  ...         (constants.GENESIS_BLOCK_NUMBER, FrontierVM),
+  ...         (HOMESTEAD_MAINNET_BLOCK, HomesteadVM),
+  ...     ),
+  ... )
+
+Then to initialize, you can start it up with an in-memory database:
+
+.. doctest::
+
+  >>> from eth.db.backends.memory import MemoryDB
+  >>> from eth.chains.mainnet import MAINNET_GENESIS_HEADER
+
+  >>> # start a fresh in-memory db
+
+  >>> # initialize a fresh chain
+  >>> chain = chain_class.from_genesis_header(MemoryDB(), MAINNET_GENESIS_HEADER)

docs/guides/eth/building_chains.rst

@@ -11,6 +11,5 @@ This section aims to provide hands-on guides to demonstrate how to use Py-EVM. I
    quickstart
    building_an_app_that_uses_pyevm
    architecture
-   building_chains
    understanding_the_mining_process
    creating_opcodes

docs/guides/eth/index.rst

@@ -1,8 +1,8 @@
 Understanding the mining process
 ================================
 
-In the :doc:`Building Chains Guide <building_chains>` we already learned how to
-use the :class:`~eth.chains.base.MiningChain` class to create a single
+From the :ref:`EVM Cookbook<evm_cookbook>` we can already learn how to
+use the :class:`~eth.chains.base.Chain` class to create a single
 blockchain as a combination of different virtual machines for different spans
 of blocks.
 
@@ -38,7 +38,9 @@ block first because, after all, one primary use case for the Ethereum blockchain
 For the sake of simplicity though, we'll mine an empty block as a first example (meaning the block
 will not contain any transactions)
 
-As a refresher, he's where we left of as part of the :doc:`Building Chains Guide </guides/eth/building_chains>`.
+As a refresher, he's how we create a chain as demonstrated in the
+:ref:`Using the chain object recipe<evm_cookbook_recipe_using_the_chain_object>` from the
+cookbook.
 
 ::
 

docs/guides/eth/understanding_the_mining_process.rst

@@ -16,6 +16,7 @@ Table of contents
    :maxdepth: 1
    :caption: Fundamentals
 
+   cookbooks/index
    guides/index
    api/index