Read the docs (#59)

* docs started

* first attempt at travis file

* add docs artifacts to gitignore

* fix ignore file

* try to fix git ignore again

* document configuration

* document other fields

* typo

* add nav in sidebar, change pygments

* added deploy info

* testing docs

* subsection

* subsection

* fix conf.py file

* New .travis setup WIP

* New .travis setup WIP

* New .travis appears to work, will merge

* Making sure we do CI + readthedocs

* Making sure we do CI + readthedocs

* describe networks section in chanterelle.json

* remove generated indices section from table of contents

* autoversion and some stubbing

* how to invoke compiler

* fix code block

* compiler and deployer invocation:

* fix shell code blocks

* genesis section

* actually add genesis-blocks.rst

* add cliquebait plug

* libraries

.gitignore

@@ -11,3 +11,4 @@
 *.swp
 /deploy.js
 /compile.js
+/docs/_build/

.travis.yml

@@ -1,9 +1,26 @@
-language: node_js
-dist: trusty
-sudo: required
-node_js: stable
-install:
-  - npm install
-  - bower install --production
-script:
-  - pulp build
+matrix:
+  include:
+    - language: node_js
+      node_js: 8
+      dist: trusty
+      sudo: required
+      node_js: stable
+      install:
+        - npm install
+        - bower install --production
+      script:
+        - pulp build
+  include:
+    - language: python
+      python: 3.5
+      install:
+        - pip install sphinx sphinx_rtd_theme
+      script:
+        - cd docs; make html
+      deploy:
+        provider: pages
+        skip_cleanup: true
+        github_token: $GITHUB_TOKEN
+        local_dir: docs/_build/html
+        on:
+          branch: read-the-docs

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = Chanterelle
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/chanterelle-json.rst

@@ -0,0 +1,97 @@
+.. _chanterelle-json:
+
+
+================
+chanterelle.json
+================
+
+A Chanterelle project is primarily described in ``chanterelle.json``, which should be placed in the root of your project.
+A sample project is defined below, based on the `parking-dao application <https://github.com/f-o-a-m/parking-dao>`_.
+
+.. code-block:: json
+
+    { "name": "parking-dao",
+      "version": "0.0.1",
+      "source-dir": "contracts",
+      "artifacts-dir": "build/contracts",
+      "modules": [ "FoamCSR"
+                 , "ParkingAuthority"
+                 , "SimpleStorage"
+                 , "User"
+                 , "ParkingAnchor"
+                 , "Nested.SimpleStorage"
+                 ],
+      "dependencies": ["zeppelin-solidity"],
+      "libraries": {
+          "FixedLib": "0x1337133713371337133713371337133713371337",
+          "AutocompiledLib": {
+              "address": "0xf00dcafe0ea7beef808080801234567890ABCDEF",
+              "code": {
+                  "file": "src/MyLibraries/AutocompiledLib.sol"
+              }
+          },
+          "InjectedLib": {
+              "address": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+              "code": {
+                  "bytecode": "0x73deadbeefdeadbeefdeadbeefdeadbeefdeadbeef301460606040..."
+              }
+          },
+          "FetchedLib": {
+              "address": "0x863df6bfa4469f3ead0be8f9f2aae51c91a907b4",
+              "via": ["mainnet", "rinkeby"]
+          }
+      },
+      "networks": {
+            "some-private-net": {
+                "url": "http://chain-1924-or-1925.roll-the-dice-see-what-you-get.com:8545/",
+                "chains": "1924,1925",
+            },
+            "a-different-net": {
+                "url": "http://mystery-chain.whose-id-always-chang.es:8545/",
+                "chains": "*",
+            }
+      },
+      "solc-output-selection": [],
+      "purescript-generator": {
+          "output-path": "src",
+          "module-prefix": "Contracts",
+          "expression-prefix": ""
+      }
+    }
+
+Specification
+-------------
+
+Note: All filepaths are relative to the ``chanterelle.json`` file, which is considered the project root.
+
+``chanterelle.json`` - specification:
+
+- ``name`` - ``Required``: The name of your project (currently unused, for future use with package management)
+- ``version`` - ``Required``: The currrent version of your project (currently unused, for future use with package management)
+- ``source-dir`` - ``Required``:  Where your Solidity contracts are located.
+- ``artifacts-dir`` - ``Optional``:  The directory where the contract artifacts (ABI, bytecode, deployment info, etc) will be written. Defaults to ``build``.
+- ``modules`` - ``Required``: A list of all solidity contracts you wish to compile (see `Modules`)
+- ``dependencies`` - ``Optional``: External Solidity (source-code) libraries/dependencies to use when compiling (see `Dependencies`).
+- ``libraries`` - ``Optional``: Solidity libraries to link against when compiling.
+    - A library may be defined as just an address. This is known as a "Fixed Library".
+      In this case, that address will be fed to solc when compiling contracts that depend on it.
+      However, generating genesis blocks will be unavailable as there is no means to get the code for the given library.
+    - A library may alternatively be defined as an address and a means to fetch the library.
+      The address will be fed into solc as with a Fixed Library, however, when generating a genesis block, Chanterelle will attempt
+      to compile the library or fetch it from any specified networks.
+    - If a library is injected as raw bytecode or fetched from a network, that code must begin with a library guard (``0x73<addr>3014``).
+      Chanterelle uses this to automagically inject the correct library address into the Genesis block.
+    - Supported networks to fetch from include: ``"mainnet"``, ``"ropsten"``, ``"rinkeby"``, ``"kovan"``, and  ``"localhost"``,
+      as well as any networks defined in the ``"networks"`` field of your project spec.
+- ``networks`` - ``Optional``: Additional networks to fetch libraries from.
+    - Each network has a required ``"url"`` field, which tells Chanterelle how to reach a node on that network
+    - Each network has a required ``"chains"`` field, which tells Chanterelle which network IDs to accept from that node. The value may either
+      be a comma-separated list of network ID numbers (still has to be a string for just one network), or ``"*"`` to accept any network ID.
+- ``solc-output-selection`` - Additional outputs to request from solc (currently unsupported, but see `solc documentation`)
+- ``purescript-generator`` - ``Required``: Options for purescript-web3-generator (see below)
+
+``purescript-generator`` - options:
+
+- ``output-path`` - ``Required``: Where to place generated PureScript source files, for example this is your PureScript project source directory.
+- ``module-prefix`` - ``Optional``: What module name to prefix to your generated PureScript bindings. Note that the generated files will be stored relative to the output path (e.g. if set to ``Contracts`` as above, code will be generated into ``src/Contracts``). Defaults to ``Contracts``.
+- ``expression-prefix`` - ``Optional``:  Prefix `all` generated functions with the specified prefix. This is useful if you are depending on external smart contract libraries that name their solidity events or functions that are invalid purescript names.

docs/compiling.rst

@@ -0,0 +1,75 @@
+.. _compiling:
+
+
+=========
+Compiling
+=========
+
+Currently, Chanterelle does not have a dedicated command line tool for invoking its functionality. Instead, one writes 
+a brief PureScript program to invoke the various features of Chanterelle.
+
+Generally, you'd want to have at least two subprojects, one for compiling and one for deploying/testing. This is because
+the deployer and test suite will surely depend on PureScript bindings generated during the compilation phase, and thus
+cannot be part of the same project. An example of this can be seen in `the Parking DAO example <https://github.com/f-o-a-m/parking-dao>`_.
+
+
+Invoking the compiler
+---------------------
+
+A sample application to invoke the compiler is presented below. This is nearly identical to the Parking DAO compile script, 
+with the exception that this script also invokes the Genesis block generator. One may leave out the ``runGenesisGenerator`` bit
+if this functionality is not required. One may want to store this script in a directory outside where their PureScript build system
+(such as Pulp) would keep code. One such location is ``compile/Compile.purs`` (as opposed to say, ``src/compile/Compile.purs``).
+
+.. code-block:: haskell
+
+    module CompileMain where
+
+    import Prelude
+    import Chanterelle (compileMain)
+    import Chanterelle.Genesis (runGenesisGenerator)
+    import Control.Monad.Aff.Console (CONSOLE)
+    import Control.Monad.Eff (Eff)
+    import Control.Monad.Eff.Exception (EXCEPTION)
+    import Control.Monad.Eff.Now (NOW)
+    import Node.FS.Aff (FS)
+    import Node.Process (PROCESS)
+    import Network.Ethereum.Web3 (ETH)
+    
+    main :: forall eff.
+          Eff
+            ( console :: CONSOLE
+            , fs :: FS
+            , process :: PROCESS
+            , exception :: EXCEPTION
+            , now :: NOW
+            , eth :: ETH
+            | eff
+            )
+            Unit
+    main = do
+      compileMain
+      runGenesisGenerator "./base-genesis-block.json" "./injected-genesis-block.json"
+
+
+We can then invoke this script as follows
+
+.. code-block:: shell
+
+    pulp build --src-path compile -m CompileMain --to compile.js && \
+    node compile.js --log-level info; \
+    rm -f compile.js
+
+
+This will compile and purescript-web3 codegen all the modules specified in ``chanterelle.json`` as well as generate a genesis block whose contents
+are those of ``./base-genesis-block.json`` with injected libraries appended into ``allocs`` and written out to ``./injected-genesis-block.json``.
+
+Note that we do not use ``pulp run`` as we then have no means to pass command line arguments to the compiler.
+
+Compiler arguments
+------------------
+
+Currently the following command line arguments are supported for the compiler phase when ran with ``compileMain``:
+
+- ``--log-level``: One of ``debug``, ``info``, ``warn``, or ``error``. Defaults to ``info``.
+  This option changes the level of logging to the console.