balsoft/ligo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Doc: add api/p2p.rst

Browse Source
This commit is contained in:
Grégoire Henry 2018-04-30 22:40:47 +02:00 committed by Benjamin Canou
parent bb2738bf12
commit a17e5d177c
15 changed files with 257 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.dockerignore
View File

@ -25,6 +25,7 @@ scripts/create_genesis/src
docs/introduction/readme.rst
docs/api/errors.rst
docs/api/rpc.rst
docs/api/p2p.rst
src/bin_client/test/LOG.*

1
.gitignore vendored
View File

@ -25,6 +25,7 @@ __pycache__
/docs/introduction/readme.rst
/docs/api/errors.rst
/docs/api/rpc.rst
/docs/api/p2p.rst
/src/bin_client/test/LOG.*

20
docs/Makefile
View File

@ -9,6 +9,8 @@ DOCGENDIR = doc_gen
DOCERRORDIR = $(DOCGENDIR)/errors
DOCRPCDIR = $(DOCGENDIR)/rpcs
DEV ?= --dev
all: html linkcheck
linkcheck:
@ -18,18 +20,26 @@ introduction/readme.rst: ../README.rst
sed 's/TEZOS/How to build and run/' $< > $@
api/errors.rst: $(DOCERRORDIR)/error_doc.ml
@jbuilder build $(DOCERRORDIR)/error_doc.exe
@cd .. && jbuilder build ${DEV} docs/$(DOCERRORDIR)/error_doc.exe
../_build/default/docs/$(DOCERRORDIR)/error_doc.exe > api/errors.rst
api/rpc.rst: $(DOCRPCDIR)/rpc_doc.ml $(DOCRPCDIR)/usage.rst $(DOCRPCDIR)/run_rpc_doc.sh
@jbuilder build $(DOCRPCDIR)/rpc_doc.exe
./$(DOCRPCDIR)/run_rpc_doc.sh > api/rpc.rst
$(DOCGENDIR)/rpc_doc.exe:
@cd .. && jbuilder build ${DEV} docs/$(DOCGENDIR)/rpc_doc.exe
api/rpc.rst: $(DOCGENDIR)/rpc_doc.exe api/rpc_usage.rst.inc
@jbuilder exec $(DOCGENDIR)/rpc_doc.exe < api/rpc_usage.rst.inc > api/rpc.rst
$(DOCGENDIR)/p2p_doc.exe:
@cd .. && jbuilder build ${DEV} docs/$(DOCGENDIR)/p2p_doc.exe
api/p2p.rst: $(DOCGENDIR)/p2p_doc.exe api/p2p_usage.rst.inc
@jbuilder exec $(DOCGENDIR)/p2p_doc.exe < api/p2p_usage.rst.inc > api/p2p.rst
.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).
html: Makefile api/errors.rst api/rpc.rst
html: Makefile api/errors.rst api/rpc.rst api/p2p.rst
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
clean:

1
docs/api/p2p_usage.rst.inc Normal file
View File

@ -0,0 +1 @@

0
docs/doc_gen/rpcs/usage.rst → docs/api/rpc_usage.rst.inc
View File

3
docs/doc_gen/errors/error_doc.ml
View File

@ -38,8 +38,7 @@ let pp_rst_h2 = pp_rst_title ~char:'*'
(* let pp_rst_h3 = pp_rst_title ~char:'='
* let pp_rst_h4 = pp_rst_title ~char:'`' *)
let string_of_err_category =
let open Error_monad in function
let string_of_err_category = function
| `Branch -> "branch"
| `Temporary -> "temporary"
| `Permanent -> "permanent"

8
docs/doc_gen/rpcs/jbuild → docs/doc_gen/jbuild
View File

@ -1,7 +1,8 @@
(jbuild_version 1)
(executable
((name rpc_doc)
(executables
((names (rpc_doc
p2p_doc))
(libraries
(tezos-base
tezos-stdlib-unix
@ -20,7 +21,8 @@
(alias
((name buildtest)
(deps (rpc_doc.exe))))
(deps (rpc_doc.exe
p2p_doc.exe))))
(alias
((name runtest_indent)

45
docs/doc_gen/node_helpers.ml Normal file
View File

@ -0,0 +1,45 @@
(**************************************************************************)
(* *)
(* Copyright (c) 2014 - 2018. *)
(* Dynamic Ledger Solutions, Inc. <contact@tezos.com> *)
(* *)
(* All rights reserved. No warranty, explicit or implicit, provided. *)
(* *)
(**************************************************************************)
let genesis : State.Chain.genesis = {
time =
Time.of_notation_exn "2018-04-17T11:46:23Z" ;
block =
Block_hash.of_b58check_exn
"BLockGenesisGenesisGenesisGenesisGenesisa52f8bUWPcg" ;
protocol =
Protocol_hash.of_b58check_exn
"ProtoGenesisGenesisGenesisGenesisGenesisGenesk612im" ;
}
let with_node f =
let run dir =
let (/) = Filename.concat in
let node_config : Node.config = {
genesis ;
patch_context = None ;
store_root = dir / "store" ;
context_root = dir / "context" ;
p2p = None ;
test_chain_max_tll = None ;
} in
Node.create
node_config
Node.default_peer_validator_limits
Node.default_block_validator_limits
Node.default_prevalidator_limits
Node.default_chain_validator_limits >>=? fun node ->
f node >>=? fun () ->
return () in
Lwt_utils_unix.with_tempdir "tezos_rpcdoc_" run >>= function
| Ok () ->
Lwt.return_unit
| Error err ->
Format.eprintf "%a@." pp_print_error err ;
Pervasives.exit 1

58
docs/doc_gen/p2p_doc.ml Normal file
View File

@ -0,0 +1,58 @@
(**************************************************************************)
(* *)
(* Copyright (c) 2014 - 2018. *)
(* Dynamic Ledger Solutions, Inc. <contact@tezos.com> *)
(* *)
(* All rights reserved. No warranty, explicit or implicit, provided. *)
(* *)
(**************************************************************************)
let protocols = [
"Alpha", "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" ;
]
let pp_pre f ppf x =
Rst.pp_raw_html ppf
(Format.asprintf "<pre>@\n%a@\n</pre>" (fun ppf () -> f ppf x) ())
let main _node =
(* Style : hack *)
Format.printf "%a@." Rst.pp_raw_html Rst.style ;
(* Script : hack *)
Format.printf "%a@." Rst.pp_raw_html Rst.script ;
(* Page title *)
Format.printf "%a" Rst.pp_h1 "P2P message format" ;
(* include/copy usage.rst from input *)
let rec loop () =
let s = read_line () in
Format.printf "%s@\n" s ;
loop () in
begin try loop () with End_of_file -> () end ;
Format.printf "@\n" ;
(* Data *)
Format.printf "%a@\n@\n%a@\n@."
Rst.pp_h2 "Block header (shell)"
(pp_pre Data_encoding.Binary_schema.pp)
(Data_encoding.Binary.describe Block_header.encoding) ;
Format.printf "%a@\n@\n%a@\n@."
Rst.pp_h2 "Operation (shell)"
(pp_pre Data_encoding.Binary_schema.pp)
(Data_encoding.Binary.describe Operation.encoding) ;
List.iter
(fun (_name, hash) ->
let hash = Protocol_hash.of_b58check_exn hash in
let (module Proto) = Registered_protocol.get_exn hash in
Format.printf "%a@\n@\n%a@\n@."
Rst.pp_h2 "Operation (alpha-specific)"
(pp_pre Data_encoding.Binary_schema.pp)
(Data_encoding.Binary.describe Proto.block_header_data_encoding) ;
Format.printf "%a@\n@\n%a@\n@."
Rst.pp_h2 "Operation (alpha-specific)"
(pp_pre Data_encoding.Binary_schema.pp)
(Data_encoding.Binary.describe Proto.operation_data_encoding) ;
)
protocols ;
return ()
let () =
Lwt_main.run (Node_helpers.with_node main)

160
docs/doc_gen/rpcs/rpc_doc.ml → docs/doc_gen/rpc_doc.ml
View File

@ -11,30 +11,6 @@ let protocols = [
"Alpha", "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" ;
]
module Rst = struct
let pp_title ~char ppf title =
let sub = String.map (fun _ -> char) title in
Format.fprintf ppf "@[<v 0>%s@ %s@ @ @]" title sub
let pp_h1 = pp_title ~char:'#'
let pp_h2 = pp_title ~char:'*'
let pp_h3 = pp_title ~char:'='
let pp_h4 = pp_title ~char:'`'
let pp_raw_html ppf str =
Format.fprintf ppf "@[<v>.. raw:: html@ @ %s@ @ @]"
(Re.Str.global_replace (Re.Str.regexp "\n") "\n " str)
let pp_html ppf f =
Format.fprintf ppf
"@[<v 2>.. raw:: html@ @ %a@]@\n@\n"
(fun ppf () -> f ppf) ()
let pp_ref ppf name = Format.fprintf ppf ".. _%s :@\n@\n" name
end
let pp_name ppf = function
| [] | [""] -> Format.pp_print_string ppf "/"
| prefix -> Format.pp_print_string ppf (String.concat "/" prefix)
@ -202,24 +178,36 @@ module Description = struct
target_ref ;
Option.iter service.input ~f: begin fun _ ->
pp_button ppf
~default:false ~shortlabel:"input" ~content:"Input format"
~default:false ~shortlabel:"input.json" ~content:"Json input"
target_ref ;
pp_button ppf
~default:false ~shortlabel:"input.bin" ~content:"Binary input"
target_ref
end ;
pp_button ppf
~default:false ~shortlabel:"output" ~content:"Output format"
~default:false ~shortlabel:"output.json" ~content:"Json output"
target_ref ;
pp_button ppf
~default:false ~shortlabel:"output.bin" ~content:"Binary output"
target_ref ;
end ;
pp_content ppf
~tag:"p" ~shortlabel:"descr" target_ref
pp_description service ;
Option.iter service.input ~f: begin fun (schema, _) ->
Option.iter service.input ~f: begin fun (schema, bin_schema) ->
pp_content ppf
~tag:"pre" ~shortlabel:"input" target_ref
~tag:"pre" ~shortlabel:"input.json" target_ref
Json_schema.pp schema ;
pp_content ppf
~tag:"pre" ~shortlabel:"input.bin" target_ref
Data_encoding.Binary_schema.pp bin_schema ;
end ;
pp_content ppf
~tag:"pre" ~shortlabel:"output" target_ref
~tag:"pre" ~shortlabel:"output.json" target_ref
Json_schema.pp (fst service.output) ;
pp_content ppf
~tag:"pre" ~shortlabel:"output.bin" target_ref
Data_encoding.Binary_schema.pp (snd service.output) ;
end
end
@ -258,83 +246,11 @@ module Description = struct
end
let style = {css|
<style>
.tab {
overflow: hidden;
border: 1px solid #ccc;
background-color: #f1f1f1;
}
.tab button {
background-color: inherit;
float: left;
border: none;
outline: none;
cursor: pointer;
padding: 5px 10px;
}
.tab button:hover {
background-color: #ddd;
}
.tab button.active {
background-color: #ccc;
}
.tabcontent {
display: none;
padding: 6px 12px;
border: 1px solid #ccc;
border-top: none;
max-height: 40ex;
margin-bottom: 7ex;
overflow: auto;
}
.tabcontent p {
margin-bottom: 12px;
}
pre {
font-size: 12px
}
.rst-content .section ul p {
margin-bottom: 0;
}
span.query {
font-family: monospace;
white-space: pre;
}
</style>
|css}
let script = {script|
<script>
function showTab(elt, tab, ref) {
var i, tabcontent, tablinks;
tabcontent = document.getElementsByClassName(ref);
for (i = 0; i < tabcontent.length; i++) {
tabcontent[i].style.display = 'none';
}
tablinks = elt.parentNode.children;
for (i = 0; i < tablinks.length; i++) {
tablinks[i].className = tablinks[i].className.replace(' active', '');
}
document.getElementById(tab).style.display = 'block';
elt.className += ' active';
}
document.addEventListener('DOMContentLoaded', function() {
var a = document.getElementsByClassName('defaultOpen');
for (i = 0; i < a.length; i++) { a[i].click() }
})
</script>
|script}
let pp_document ppf descriptions =
(* Style : hack *)
Format.fprintf ppf "%a@." Rst.pp_raw_html style ;
Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.style ;
(* Script : hack *)
Format.fprintf ppf "%a@." Rst.pp_raw_html script ;
Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.script ;
(* Page title *)
Format.fprintf ppf "%a" Rst.pp_h1 "RPC API" ;
(* include/copy usage.rst from input *)
@ -363,33 +279,7 @@ let pp_document ppf descriptions =
Format.fprintf ppf "%a@\n@\n" (Description.pp prefix) rpc_dir)
descriptions
let genesis : State.Chain.genesis = {
time =
Time.of_notation_exn "2018-04-17T11:46:23Z" ;
block =
Block_hash.of_b58check_exn
"BLockGenesisGenesisGenesisGenesisGenesisa52f8bUWPcg" ;
protocol =
Protocol_hash.of_b58check_exn
"ProtoGenesisGenesisGenesisGenesisGenesisGenesk612im" ;
}
let main dir =
let (/) = Filename.concat in
let node_config : Node.config = {
genesis ;
patch_context = None ;
store_root = dir / "store" ;
context_root = dir / "context" ;
p2p = None ;
test_chain_max_tll = None ;
} in
Node.create
node_config
Node.default_peer_validator_limits
Node.default_block_validator_limits
Node.default_prevalidator_limits
Node.default_chain_validator_limits >>=? fun node ->
let main node =
let shell_dir = Node.build_rpc_directory node in
let protocol_dirs =
List.map
@ -412,12 +302,4 @@ let main dir =
return ()
let () =
Lwt_main.run begin
Lwt_utils_unix.with_tempdir "tezos_rpcdoc_" main >>= function
| Ok _ ->
Lwt.return_unit
| Error err ->
Format.eprintf "%a@." pp_print_error err ;
Pervasives.exit 1
end
Lwt_main.run (Node_helpers.with_node main)

19
docs/doc_gen/rpcs/run_rpc_doc.sh
View File

@ -1,19 +0,0 @@
#!/bin/bash
set -e
set -o pipefail
#**************************************************************************#
#* *#
#* Copyright (c) 2014 - 2018. *#
#* Dynamic Ledger Solutions, Inc. <contact@tezos.com> *#
#* *#
#* All rights reserved. No warranty, explicit or implicit, provided. *#
#* *#
#**************************************************************************#
docgen_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && echo "$(pwd -P)")"
rpc_doc="../_build/default/docs/doc_gen/rpcs/rpc_doc.exe"
usage="$docgen_dir/usage.rst"
$rpc_doc < $usage | sed -e 's|/chains/main/blocks/head/|.../<block_id>/|g'

101
docs/doc_gen/rst.ml Normal file
View File

@ -0,0 +1,101 @@
(**************************************************************************)
(* *)
(* Copyright (c) 2014 - 2018. *)
(* Dynamic Ledger Solutions, Inc. <contact@tezos.com> *)
(* *)
(* All rights reserved. No warranty, explicit or implicit, provided. *)
(* *)
(**************************************************************************)
let pp_title ~char ppf title =
let sub = String.map (fun _ -> char) title in
Format.fprintf ppf "@[<v 0>%s@ %s@ @ @]" title sub
let pp_h1 = pp_title ~char:'#'
let pp_h2 = pp_title ~char:'*'
let pp_h3 = pp_title ~char:'='
let pp_h4 = pp_title ~char:'`'
let pp_raw_html ppf str =
Format.fprintf ppf "@[<v>.. raw:: html@ @ %s@ @ @]"
(Re.Str.global_replace (Re.Str.regexp "\n") "\n " str)
let pp_html ppf f =
Format.fprintf ppf
"@[<v 2>.. raw:: html@ @ %a@]@\n@\n"
(fun ppf () -> f ppf) ()
let pp_ref ppf name = Format.fprintf ppf ".. _%s :@\n@\n" name
let style = {css|
<style>
.tab {
overflow: hidden;
border: 1px solid #ccc;
background-color: #f1f1f1;
}
.tab button {
background-color: inherit;
float: left;
border: none;
outline: none;
cursor: pointer;
padding: 5px 10px;
}
.tab button:hover {
background-color: #ddd;
}
.tab button.active {
background-color: #ccc;
}
.tabcontent {
display: none;
padding: 6px 12px;
border: 1px solid #ccc;
border-top: none;
max-height: 40ex;
margin-bottom: 7ex;
overflow: auto;
}
.tabcontent p {
margin-bottom: 12px;
}
pre {
font-size: 12px
}
.rst-content .section ul p {
margin-bottom: 0;
}
span.query {
font-family: monospace;
white-space: pre;
}
</style>
|css}
let script = {script|
<script>
function showTab(elt, tab, ref) {
var i, tabcontent, tablinks;
tabcontent = document.getElementsByClassName(ref);
for (i = 0; i < tabcontent.length; i++) {
tabcontent[i].style.display = 'none';
}
tablinks = elt.parentNode.children;
for (i = 0; i < tablinks.length; i++) {
tablinks[i].className = tablinks[i].className.replace(' active', '');
}
document.getElementById(tab).style.display = 'block';
elt.className += ' active';
}
document.addEventListener('DOMContentLoaded', function() {
var a = document.getElementsByClassName('defaultOpen');
for (i = 0; i < a.length; i++) { a[i].click() }
})
</script>
|script}

5
src/lib_base/fitness.ml
View File

@ -53,8 +53,9 @@ let rec pp fmt = function
let encoding =
let open Data_encoding in
def "fitness"
~title: "Tezos block fitness"
(list bytes)
~title: "Fitness"
~description: "... FIXME ..."
(list (def "fitness.elem" bytes))
let to_bytes v = Data_encoding.Binary.to_bytes_exn encoding v
let of_bytes b = Data_encoding.Binary.of_bytes encoding b

2
src/lib_crypto/helpers.ml
View File

@ -103,7 +103,7 @@ module MakeEncoder(H : sig
~binary:
H.raw_encoding
~json:
(def H.title
(def H.name
~title: (H.title ^ " (Base58Check-encoded)") @@
conv
H.to_b58check

2
src/proto_alpha/lib_protocol/src/seed_repr.ml
View File

@ -14,7 +14,7 @@ type t = T of State_hash.t
type sequence = S of State_hash.t
type nonce = MBytes.t
let nonce_encoding = Data_encoding.bytes
let nonce_encoding = Data_encoding.Fixed.bytes Constants_repr.nonce_length
let init = "1234567890123456789012"
let zero_bytes = MBytes.of_string (String.make Nonce_hash.size '\000')