Create a complete, user-friendly and up-to-date documentation

[cburgdorf]

This is a fresh attempt to organize efforts to release a complete, user friendly and up to date documentation. I know that we already have two existing (https://github.com/ethereum/py-evm/issues/19, https://github.com/ethereum/py-evm/issues/177) github issues regarding documentation and the existing content was (and further will be) incorporated in this issue.

Since it is planned that I'll be dedicating a significant amount of my time to the documentation I wanted to set up a new issue that I can maintain and keep up to date as I go. In that sense, this ticket should supersede the existing two tickets and I propose that we close them.

References

We include a collection of links to other ethereum client documentations here as a reference. There may be further links to existing docs directly included in the table of contents.

• Geth Documentation
• Parity Documentation
• Ethereum Harmony Documentation
• cpp-ethereum Documentation

Other inspirations

• Trio Docs (Nice rtd gems)
• Solidity docs
• gotdotengine (nice rtd gems)
• Would be nice to have these copy-n-past'able terminal demos in the guide

Style / Prose / Grammar

The documentation should follow a common style in regard to grammar, wording and structure. It's planned to flesh out some basic rules but for now, a lot of great rules can be derived from this style guide by Adobe.

Audience

We assume the audience of readers will range from regular blockchain enthusiasts to dApp developers as well as protocol engineers and scientists.

Outline

The following outline assumes (which is debatable as everything) that we will clearly communicate the different roles of Trinity and Py-EVM but will still maintain a common end point to host the documentation.

Index

High level description of the library. Links to github repository, gitter chat channel, table of contents for the remainder of the documentation.

• Introduction

  • Overview
  • Project goals
  • Role of Trinity and Py-EVM

• Installation (Geth Example)

  • Using pip
  • From source
  • …

• QuickStart

  • Syncing with the Mainnet (Parity Example)

• Fundamentals

  • Architectural Overview

  • Guides

    • Trinity
      • Basic usage
      • ...
    • EVM
      • Basics
      • Creating or extending an EVM
      • Creating new Opcodes
      • Composing Opcodes into VMs
      • Composing VMs into the EVM
      • Understanding the transaction processing
      • ...

  • API

    • Trinity
      • ...
    • EVM
      • EVM
      • VM
      • Computation
      • Gas Meter
      • CodeStream
      • Memory
      • Message
      • Stack
      • Opcode
      • ...

• Contributing

  • How to setup the code base and run the tests
  • Style Guide
  • Creating Pull Requests

• Code of Conduct (Trio Example, MachineLabs example)

API Docs

API docs are read directly from source using sphinx autodoc feature. To achieve a high quality and common style of API docs all API docs should follow this structure.

def add_transaction(self,
                    transaction: BaseTransaction,
                    computation: BaseComputation,
                    block: BaseBlock) -> Tuple[Block, Dict[bytes, bytes]]:
        """
        Add a transaction to the given block and
        return `trie_data` to store the transaction data in chaindb in VM layer.

        Update the bloom_filter, transaction trie and receipt trie roots, bloom_filter,
        bloom, and used_gas of the block.

        :param transaction: the executed transaction
        :param computation: the Computation object with executed result
        :param block: the Block which the transaction is added in
        
        :return: the block and the trie_data
        """

Notice how the :param: and :return: directives are being used to describe parameters and return value. Usage of :type: and :rtype: directives on the other hand is discouraged as these types are directly read from the source code type definitions and already handled properly by sphinx making any further use of :type and :rtype obsolete and unnecessarily verbose.

[cburgdorf]

Some quick dumps to not forget

https://github.com/ethereum/py-evm/pull/581#discussion_r183897290

https://github.com/ethereum/py-evm/pull/633#issuecomment-386278185

Tutorial ideas:

• how I would run a series of transactions that store and retrieve data from state (Gitter chat)
• how I'd deploy a contract and get back the address of the deployed code (Gitter chat)

[pipermerriam]

Suggestion for code of conduct.

https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[glaksmono]

Syncing with the Mainnet

Syncing with Testnet (Ropsten or Infura), with an example of code that communicate with the Testnet would be nice

[cburgdorf]

How to see which opcodes are applied https://github.com/ethereum/py-evm/issues/1801#issuecomment-514226811