From a17e5d177c5eb31d85c78a883d53797b0d992cab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Henry?= Date: Mon, 30 Apr 2018 22:40:47 +0200 Subject: [PATCH] Doc: add `api/p2p.rst` --- .dockerignore | 1 + .gitignore | 1 + docs/Makefile | 20 ++- docs/api/p2p_usage.rst.inc | 1 + .../rpcs/usage.rst => api/rpc_usage.rst.inc} | 0 docs/doc_gen/errors/error_doc.ml | 9 +- docs/doc_gen/{rpcs => }/jbuild | 8 +- docs/doc_gen/node_helpers.ml | 45 +++++ docs/doc_gen/p2p_doc.ml | 58 +++++++ docs/doc_gen/{rpcs => }/rpc_doc.ml | 160 +++--------------- docs/doc_gen/rpcs/run_rpc_doc.sh | 19 --- docs/doc_gen/rst.ml | 101 +++++++++++ src/lib_base/fitness.ml | 5 +- src/lib_crypto/helpers.ml | 2 +- src/proto_alpha/lib_protocol/src/seed_repr.ml | 2 +- 15 files changed, 257 insertions(+), 175 deletions(-) create mode 100644 docs/api/p2p_usage.rst.inc rename docs/{doc_gen/rpcs/usage.rst => api/rpc_usage.rst.inc} (100%) rename docs/doc_gen/{rpcs => }/jbuild (84%) create mode 100644 docs/doc_gen/node_helpers.ml create mode 100644 docs/doc_gen/p2p_doc.ml rename docs/doc_gen/{rpcs => }/rpc_doc.ml (72%) delete mode 100755 docs/doc_gen/rpcs/run_rpc_doc.sh create mode 100644 docs/doc_gen/rst.ml diff --git a/.dockerignore b/.dockerignore index edc2ba48d..c53ecea5a 100644 --- a/.dockerignore +++ b/.dockerignore @@ -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.* diff --git a/.gitignore b/.gitignore index 79099dc4e..84c9cdf53 100644 --- a/.gitignore +++ b/.gitignore @@ -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.* diff --git a/docs/Makefile b/docs/Makefile index 8d659e4be..e257ca05d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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: diff --git a/docs/api/p2p_usage.rst.inc b/docs/api/p2p_usage.rst.inc new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/docs/api/p2p_usage.rst.inc @@ -0,0 +1 @@ + diff --git a/docs/doc_gen/rpcs/usage.rst b/docs/api/rpc_usage.rst.inc similarity index 100% rename from docs/doc_gen/rpcs/usage.rst rename to docs/api/rpc_usage.rst.inc diff --git a/docs/doc_gen/errors/error_doc.ml b/docs/doc_gen/errors/error_doc.ml index 481983433..91f53836c 100644 --- a/docs/doc_gen/errors/error_doc.ml +++ b/docs/doc_gen/errors/error_doc.ml @@ -38,11 +38,10 @@ 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 - | `Branch -> "branch" - | `Temporary -> "temporary" - | `Permanent -> "permanent" +let string_of_err_category = function + | `Branch -> "branch" + | `Temporary -> "temporary" + | `Permanent -> "permanent" let make_counter () = let i = ref 1 in diff --git a/docs/doc_gen/rpcs/jbuild b/docs/doc_gen/jbuild similarity index 84% rename from docs/doc_gen/rpcs/jbuild rename to docs/doc_gen/jbuild index 9f86e2c04..79c96ce6e 100644 --- a/docs/doc_gen/rpcs/jbuild +++ b/docs/doc_gen/jbuild @@ -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) diff --git a/docs/doc_gen/node_helpers.ml b/docs/doc_gen/node_helpers.ml new file mode 100644 index 000000000..13eab5562 --- /dev/null +++ b/docs/doc_gen/node_helpers.ml @@ -0,0 +1,45 @@ +(**************************************************************************) +(* *) +(* Copyright (c) 2014 - 2018. *) +(* Dynamic Ledger Solutions, Inc. *) +(* *) +(* 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 diff --git a/docs/doc_gen/p2p_doc.ml b/docs/doc_gen/p2p_doc.ml new file mode 100644 index 000000000..949187fd0 --- /dev/null +++ b/docs/doc_gen/p2p_doc.ml @@ -0,0 +1,58 @@ +(**************************************************************************) +(* *) +(* Copyright (c) 2014 - 2018. *) +(* Dynamic Ledger Solutions, Inc. *) +(* *) +(* 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 "
@\n%a@\n
" (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) diff --git a/docs/doc_gen/rpcs/rpc_doc.ml b/docs/doc_gen/rpc_doc.ml similarity index 72% rename from docs/doc_gen/rpcs/rpc_doc.ml rename to docs/doc_gen/rpc_doc.ml index f0709c005..155bcfa89 100644 --- a/docs/doc_gen/rpcs/rpc_doc.ml +++ b/docs/doc_gen/rpc_doc.ml @@ -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 "@[%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 "@[.. raw:: html@ @ %s@ @ @]" - (Re.Str.global_replace (Re.Str.regexp "\n") "\n " str) - - let pp_html ppf f = - Format.fprintf ppf - "@[.. 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| - -|css} - -let script = {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) diff --git a/docs/doc_gen/rpcs/run_rpc_doc.sh b/docs/doc_gen/rpcs/run_rpc_doc.sh deleted file mode 100755 index 5b96c65ea..000000000 --- a/docs/doc_gen/rpcs/run_rpc_doc.sh +++ /dev/null @@ -1,19 +0,0 @@ -#!/bin/bash - -set -e -set -o pipefail - -#**************************************************************************# -#* *# -#* Copyright (c) 2014 - 2018. *# -#* Dynamic Ledger Solutions, Inc. *# -#* *# -#* 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/|...//|g' diff --git a/docs/doc_gen/rst.ml b/docs/doc_gen/rst.ml new file mode 100644 index 000000000..90ec77bd3 --- /dev/null +++ b/docs/doc_gen/rst.ml @@ -0,0 +1,101 @@ +(**************************************************************************) +(* *) +(* Copyright (c) 2014 - 2018. *) +(* Dynamic Ledger Solutions, Inc. *) +(* *) +(* 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 "@[%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 "@[.. raw:: html@ @ %s@ @ @]" + (Re.Str.global_replace (Re.Str.regexp "\n") "\n " str) + +let pp_html ppf f = + Format.fprintf ppf + "@[.. raw:: html@ @ %a@]@\n@\n" + (fun ppf () -> f ppf) () + +let pp_ref ppf name = Format.fprintf ppf ".. _%s :@\n@\n" name + + + +let style = {css| + +|css} + +let script = {script| + +|script} diff --git a/src/lib_base/fitness.ml b/src/lib_base/fitness.ml index 935241df2..7bf88ca35 100644 --- a/src/lib_base/fitness.ml +++ b/src/lib_base/fitness.ml @@ -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 diff --git a/src/lib_crypto/helpers.ml b/src/lib_crypto/helpers.ml index 131c9ff2b..4c0094d8e 100644 --- a/src/lib_crypto/helpers.ml +++ b/src/lib_crypto/helpers.ml @@ -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 diff --git a/src/proto_alpha/lib_protocol/src/seed_repr.ml b/src/proto_alpha/lib_protocol/src/seed_repr.ml index d210d7971..9011a5812 100644 --- a/src/proto_alpha/lib_protocol/src/seed_repr.ml +++ b/src/proto_alpha/lib_protocol/src/seed_repr.ml @@ -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')