Merge pull request #3 from AdrienChampion/master

better output + user doc update
OCamlPro · Mar 1, 2019 · 73d7bdf · 73d7bdf
2 parents 3ad1b5f + 375c0cb
commit 73d7bdf
Show file tree

Hide file tree

Showing 186 changed files with 27,706 additions and 603 deletions.
diff --git a/Makefile b/Makefile
@@ -19,6 +19,9 @@ user-doc:
 test: bin-test doc-test
 
 doc: user-doc
+	cp README.md docs/index.md
+
+pre-commit: test doc user-doc
 
 clean:
 	dune clean
diff --git a/README.md b/README.md
@@ -1,43 +1,52 @@
-# techelson
+# Techelson
 
 TEst miCHELSON: `techelson`
 
 A test execution engine for Michelson smart contracts.
 
+# Documentation
+
+The user documentation is hosted here: [liquidity-lang.org/techelson/doc]. You can also access the bleeding edge version on [the main repo's git page]. Finally, there is a blog post by Techelson's main developer on how to use Techelson with [Liquidity]: [adrienchampion.github.io/blog].
+
 # Features
 
 Techelson is currently in beta. The rough list of (planned) features is
 
 - [x] operation must-fail: specifies that a (chain of) operation(s) should fail
 - [x] inspection instruction: break points and stack inspection
-- [x] support for all data types (potentially with some liberty taken compared to tezos)
+- [ ] support for all data types (potentially with some liberty taken compared to tezos)
+    - [x] everything but `signature`
+    - [ ] `signature`
 - [ ] semantics as close to the tezos protocol as possible
-    - [x] for non-crypto operations (`int`, `nat`, `map`, *etc.*)
+    - [x] for non-crypto, non-packing-related operations (`int`, `nat`, `map`, *etc.*)
     - [ ] for crypto operations
+    - [x] internal packing and unpacking (packed and unpacked by Techelson)
+    - [ ] arbitrary byte unpacking
 - [x] support import of local michelson contracts
 - [ ] support retrieving the storage and code of contracts directly from the tezos blockchain
 
 # Build
 
-We recommend to use the latest version of the OCaml compiler. For example
+We recommend to use the latest version of the OCaml compiler. Make sure you have [opam installed],
+and run
 
 ```bash
 > opam switch create techelson 4.07.1
 ```
 
-`techelson`relies on the [dune] build system and a few other libraries:
+Techelson relies on the [dune] build system and a few other libraries:
 
 ```bash
 > opam install dune menhir zarith ptime
 ```
 
-(This list of dependencies might be out-of-date. Check `.travis.sh` for the latest version.) Finally, build `techelson` with `make`. The binary will be `./bin/techelson`.
+(This list of dependencies might be out-of-date. Check `.travis.sh` for the latest version.) Finally, build Techelson with `make`. The binary will be `./bin/techelson`.
 
-You can also run `make test` to make sure there is no problem with the techelson binary. The user documentation's root is `docs/user_doc/index.html`. You can regenerate it with `make user-doc`, as long as you have [mdbook] installed.
+You can also run `make test` to make sure there is no problem with the Techelson binary. The user documentation's root is `docs/user_doc/index.html`. You can regenerate it with `make user-doc`, as long as you have [mdbook] installed.
 
 # Usage
 
-Assuming the binary `techelson` is in you path, you can run it with
+Assuming the binary Techelson is in you path, you can run it with
 
 ```bash
 > techelson [ --contract <contract_file> <optional_init_file> ]* -- [ <testcase> ]*
@@ -53,13 +62,10 @@ For example
 > techelson --contract rsc/tests/test0/contracts/test0.liq.tz -- rsc/tests/test0/okay/Test0Test1.techel
 ```
 
-# Documentation
-
-The user documentation is hosted here: [liquidity-lang.org/techelson/doc]. You can also access the bleeding edge version on [the main repo's git page]. Finally, there is a blog post by techelson's main developer on how to use techelson with [Liquidity]: [adrienchampion.github.io/blog].
-
-[dune]: https://github.com/ocaml/dune (Dune project manager's Github page)
-[mdbook]: https://github.com/rust-lang-nursery/mdBook (Mdbook's github repository)
-[liquidity-lang.org/techelson/doc]: http://www.liquidity-lang.org/techelson/doc (Techelson's user documentation)
-[Liquidity]: http://www.liquidity-lang.org/ (Liquidity's official page)
-[adrienchampion.github.io/blog]: https://adrienchampion.github.io/blog/tezos/techelson/with_liquidity/index.html (Using techelson with Liquidity)
-[the main repo's git page]: https://ocamlpro.github.io/techelson/user_doc (Techelson's user documentation)
+[opam installed]: https://opam.ocaml.org/doc/Install.html
+[dune]: https://github.com/ocaml/dune
+[mdbook]: https://github.com/rust-lang-nursery/mdBook
+[liquidity-lang.org/techelson/doc]: http://www.liquidity-lang.org/techelson/doc
+[Liquidity]: http://www.liquidity-lang.org/
+[adrienchampion.github.io/blog]: https://adrienchampion.github.io/blog/tezos/techelson/with_liquidity/index.html
+[the main repo's git page]: https://ocamlpro.github.io/techelson/user_doc
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1 +1 @@
-theme: jekyll-theme-midnight
+theme: jekyll-theme-leap-day
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,71 @@
+# Techelson
+
+TEst miCHELSON: `techelson`
+
+A test execution engine for Michelson smart contracts.
+
+# Documentation
+
+The user documentation is hosted here: [liquidity-lang.org/techelson/doc]. You can also access the bleeding edge version on [the main repo's git page]. Finally, there is a blog post by Techelson's main developer on how to use Techelson with [Liquidity]: [adrienchampion.github.io/blog].
+
+# Features
+
+Techelson is currently in beta. The rough list of (planned) features is
+
+- [x] operation must-fail: specifies that a (chain of) operation(s) should fail
+- [x] inspection instruction: break points and stack inspection
+- [ ] support for all data types (potentially with some liberty taken compared to tezos)
+    - [x] everything but `signature`
+    - [ ] `signature`
+- [ ] semantics as close to the tezos protocol as possible
+    - [x] for non-crypto, non-packing-related operations (`int`, `nat`, `map`, *etc.*)
+    - [ ] for crypto operations
+    - [x] internal packing and unpacking (packed and unpacked by Techelson)
+    - [ ] arbitrary byte unpacking
+- [x] support import of local michelson contracts
+- [ ] support retrieving the storage and code of contracts directly from the tezos blockchain
+
+# Build
+
+We recommend to use the latest version of the OCaml compiler. Make sure you have [opam installed],
+and run
+
+```bash
+> opam switch create techelson 4.07.1
+```
+
+Techelson relies on the [dune] build system and a few other libraries:
+
+```bash
+> opam install dune menhir zarith ptime
+```
+
+(This list of dependencies might be out-of-date. Check `.travis.sh` for the latest version.) Finally, build Techelson with `make`. The binary will be `./bin/techelson`.
+
+You can also run `make test` to make sure there is no problem with the Techelson binary. The user documentation's root is `docs/user_doc/index.html`. You can regenerate it with `make user-doc`, as long as you have [mdbook] installed.
+
+# Usage
+
+Assuming the binary Techelson is in you path, you can run it with
+
+```bash
+> techelson [ --contract <contract_file> <optional_init_file> ]* -- [ <testcase> ]*
+```
+
+Argument `<contract_file>` is a michelson contract (`storage`, `parameter` and `code` fields). `<optional_init_file>` is an optional initializer for the contract. It should contain two fields : `parameter` and `code`. The former is the type of data the initializer takes as input, and the latter is a (sequence of) michelson instruction(s) which, from a stack with a value of type `parameter`, produces a stack with a value of the `storage` type appearing in the `<contract_file>` associated with the initializer.
+
+A `<testcase>` is a (sequence of) michelson instruction(s) which produce(s) a list of `operation`s from an empty stack. Techelson runs all testcases sequentially and reports the errors it runs into.
+
+For example
+
+```bash
+> techelson --contract rsc/tests/test0/contracts/test0.liq.tz -- rsc/tests/test0/okay/Test0Test1.techel
+```
+
+[opam installed]: https://opam.ocaml.org/doc/Install.html
+[dune]: https://github.com/ocaml/dune
+[mdbook]: https://github.com/rust-lang-nursery/mdBook
+[liquidity-lang.org/techelson/doc]: http://www.liquidity-lang.org/techelson/doc
+[Liquidity]: http://www.liquidity-lang.org/
+[adrienchampion.github.io/blog]: https://adrienchampion.github.io/blog/tezos/techelson/with_liquidity/index.html
+[the main repo's git page]: https://ocamlpro.github.io/techelson/user_doc
diff --git a/docs/user_doc/index.html b/docs/user_doc/index.html
@@ -30,11 +30,11 @@
 
 
     </head>
-    <body class="navy">
+    <body class="light">
         <!-- Provide site root to javascript -->
         <script type="text/javascript">
             var path_to_root = "";
-            var default_theme = "navy";
+            var default_theme = "light";
         </script>
 
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
@@ -92,10 +92,10 @@
                                 <i class="fa fa-paint-brush"></i>
                             </button>
                             <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
-                                <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
-                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy (default)</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                             </ul>
 

diff --git a/docs/user_doc/michelson/index.html b/docs/user_doc/michelson/index.html
@@ -30,11 +30,11 @@
 
 
     </head>
-    <body class="navy">
+    <body class="light">
         <!-- Provide site root to javascript -->
         <script type="text/javascript">
             var path_to_root = "../";
-            var default_theme = "navy";
+            var default_theme = "light";
         </script>
 
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
@@ -92,10 +92,10 @@
                                 <i class="fa fa-paint-brush"></i>
                             </button>
                             <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
-                                <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
-                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy (default)</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                             </ul>
 

diff --git a/docs/user_doc/michelson/simple_example.html b/docs/user_doc/michelson/simple_example.html
@@ -30,11 +30,11 @@
 
 
     </head>
-    <body class="navy">
+    <body class="light">
         <!-- Provide site root to javascript -->
         <script type="text/javascript">
             var path_to_root = "../";
-            var default_theme = "navy";
+            var default_theme = "light";
         </script>
 
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
@@ -92,10 +92,10 @@
                                 <i class="fa fa-paint-brush"></i>
                             </button>
                             <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
-                                <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
-                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy (default)</button></li>
+                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                                 <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                             </ul>