From eb78c2ae8c1e9557aa44d73303ee184ca8c5b8e0 Mon Sep 17 00:00:00 2001 From: Vincent Botbol Date: Thu, 19 Apr 2018 17:26:12 +0200 Subject: [PATCH] Docs/RPC: add query item display --- docs/doc_gen/rpcs/rpc_doc.ml | 66 +++++++++++++++++++++++++++----- docs/doc_gen/rpcs/run_rpc_doc.sh | 4 +- docs/doc_gen/rpcs/sandbox.json | 14 ------- 3 files changed, 58 insertions(+), 26 deletions(-) delete mode 100644 docs/doc_gen/rpcs/sandbox.json diff --git a/docs/doc_gen/rpcs/rpc_doc.ml b/docs/doc_gen/rpcs/rpc_doc.ml index 8b89c9d40..3aaf1f745 100644 --- a/docs/doc_gen/rpcs/rpc_doc.ml +++ b/docs/doc_gen/rpcs/rpc_doc.ml @@ -11,6 +11,7 @@ type service_repr = { path : string list ; meth : Resto.meth ; description : string ; + query : Resto.Description.query_item list ; input : Json_schema.schema option ; output : Json_schema.schema option ; example : string option ; @@ -42,8 +43,10 @@ let normalize_json_schema = function let repr_of_service path RPC_description.{ description ; error ; - meth ; input ; output ; _ } : service_repr = - { path ; meth ; + meth ; input ; output ; + query ; _ } : service_repr = + + { path ; meth ; query ; description = make_descr description ; input = normalize_json_schema input ; output = normalize_json_schema (Some output) ; @@ -83,12 +86,11 @@ let rec pp_print_service_tree fmt = function fprintf fmt "@]" let make_tree cctxt path = - (* TODO : add automatic example generation *) let open RPC_description in describe cctxt ~recurse:true path >>=? fun dir -> let rec loop path : _ directory -> service_tree list = function | Dynamic descr -> - [ Node ({ path ; meth=`POST ; + [ Node ({ path ; meth=`POST ; query = [] ; description=make_descr descr ; input = None ; output = None ; example = None ; error = None }, []) ] @@ -161,7 +163,7 @@ let rec pp_print_hierarchy fmt = else begin let name = "/" ^ List.hd (List.rev path) in - let offset = max 2 (String.length name / 2) in + let offset = max 4 (String.length name / 2) in if List.length l = 0 then pp_open_vbox fmt 0 @@ -277,6 +279,40 @@ let rec pp_print_rst_hierarchy fmt ~title node = in loop fmt node +let pp_print_query_arg fmt = + let open RPC_arg in + function { name ; _ } -> + fprintf fmt "<%s>" name + +let pp_print_query_html_arg fmt = + let open RPC_arg in + function { name ; _ } -> + fprintf fmt "<%s>" name + +let pp_print_query_title fmt = + let open RPC_description in + function {name ; kind ; _ } -> + match kind with + | Single arg -> fprintf fmt "%s=%a" name pp_print_query_arg arg + | Optional arg -> fprintf fmt "[%s=%a]" name pp_print_query_arg arg + | Flag -> fprintf fmt "%s" name + | Multi arg -> fprintf fmt "(%s=%a)\\*" name pp_print_query_arg arg + +let pp_print_query_item_descr fmt = + let open RPC_description in + function { name ; description ; kind } -> + begin match kind with + | Single arg -> fprintf fmt "%s : %a" name pp_print_query_html_arg arg + | Optional arg -> fprintf fmt "[%s : %a] - Optional" name pp_print_query_html_arg arg + | Flag -> fprintf fmt "%s - Flag" name + | Multi arg -> fprintf fmt "(%s : %a)\\* - Can be given multiple times" name + pp_print_query_html_arg arg + end; + begin match description with + | None -> () + | Some descr -> fprintf fmt " : %s" descr + end + let pp_print_html_tab_button fmt ?(default=false) ~shortlabel ~content path = let target_ref = ref_of_path path in fprintf fmt "@ " @@ -292,7 +328,7 @@ let pp_print_html_tab_content fmt ~tag ~shortlabel ~pp_content ~content path = fprintf fmt "<%s>@ %a@ " tag pp_content content tag; fprintf fmt "@]" -let pp_print_html_tabs fmt { path ; description ; input ; output ; _ (* example ; error *) } = +let pp_print_html_tabs fmt { path ; description ; input ; output ; query ; _ (* example ; error *) } = fprintf fmt "@[.. raw:: html@ @ "; fprintf fmt "@[
@ "; @@ -311,8 +347,16 @@ let pp_print_html_tabs fmt { path ; description ; input ; output ; _ (* example * | None -> ()); *) fprintf fmt "
@]@ "; + let query_item_list = + if query <> [] then + asprintf "

Optional query arguments :

  • %a
" + (pp_print_list + ~pp_sep:(fun fmt () -> fprintf fmt "
  • ") + pp_print_query_item_descr) query + else "" + in fprintf fmt "%a@ " (pp_print_html_tab_content ~tag:"p" ~shortlabel:"descr" - ~pp_content:pp_print_string ~content:description) path; + ~pp_content:pp_print_string ~content:(description^query_item_list)) path; (match input with | Some x -> fprintf fmt "%a@ " (pp_print_html_tab_content ~tag:"pre" ~shortlabel:"input" ~pp_content:Json_schema.pp ~content:x) path; @@ -328,11 +372,13 @@ let pp_print_html_tabs fmt { path ; description ; input ; output ; _ (* example fprintf fmt "@]" -let pp_print_rst_full_service fmt ({ path ; meth } as repr) = - fprintf fmt ".. _%s :@\n@\n**%s %s**@\n@\n" +let pp_print_rst_full_service fmt ({ path ; meth ; query } as repr) = + fprintf fmt ".. _%s :@\n@\n**%s %s%s%a**@\n@\n" (ref_of_path path) (Resto.string_of_meth meth) - ("/" ^ String.concat "/" path); + ("/" ^ String.concat "/" path) + (if query = [] then "" else "?") + (pp_print_list ~pp_sep:(fun fmt () -> fprintf fmt "&") pp_print_query_title) query; fprintf fmt "%a" pp_print_html_tabs repr let rec pp_print_rst_service_tree fmt node = diff --git a/docs/doc_gen/rpcs/run_rpc_doc.sh b/docs/doc_gen/rpcs/run_rpc_doc.sh index e3ccee91f..bbe627f84 100755 --- a/docs/doc_gen/rpcs/run_rpc_doc.sh +++ b/docs/doc_gen/rpcs/run_rpc_doc.sh @@ -22,7 +22,7 @@ tezos_init_sandboxed_client="${3:-$docgen_dir/../../../src/bin_client/tezos-init local_node="${2:-$docgen_dir/../../../_build/default/src/bin_node/main.exe}" local_client="${2:-$docgen_dir/../../../_build/default/src/bin_client/main_client.exe}" -sandbox_file="$docgen_dir/sandbox.json" +sandbox_file="/tmp/sandbox.json" usage="$docgen_dir/usage.rst" source $tezos_sandboxed_node @@ -53,4 +53,4 @@ activate_alpha >&2 sleep 2 -$rpc_doc $rpc < $usage | sed 's|/blocks/head/|/blocks//|g' +$rpc_doc $rpc < $usage | sed -e 's|/chains/main/blocks/head/|...//|g' diff --git a/docs/doc_gen/rpcs/sandbox.json b/docs/doc_gen/rpcs/sandbox.json deleted file mode 100644 index be91a4281..000000000 --- a/docs/doc_gen/rpcs/sandbox.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "genesis_pubkey": - "edpkuSLWfVU1Vq7Jg9FucPyKmma6otcMHac9zG4oU1KMHSTBpJuGQ2", - "bootstrap_keys": [ - "edpkuBknW28nW72KG6RoHtYW7p12T6GKc7nAbwYX5m8Wd9sDVC9yav", - "edpktzNbDAUjUk697W7gYg2CRuBQjyPxbEg8dLccYYwKSKvkPvjtV9", - "edpkuTXkJDGcFd5nh6VvMz8phXxU3Bi7h6hqgywNFi1vZTfQNnS1RV", - "edpkuFrRoDSEbJYgxRtLx2ps82UdaYc1WwfS9sE11yhauZt5DgCHbU", - "edpkv8EUUH68jmo3f7Um5PezmfGrRF24gnfLpH3sVNwJnV5bVCxL2n" - ], - "slot_durations" : [ 1, 0 ], - "cycle_length" : 128, - "first_free_baking_slot" : 4 -}