From 3befd156275977156e551081550a6c73e1359d03 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 2 Oct 2023 14:54:05 +0200 Subject: [PATCH 1/3] Manifest: generate [docs/doc_gen/dune] --- docs/doc_gen/dune | 55 ++++++++++++++++++++++++++--------------------- manifest/main.ml | 25 ++++++++++++++++++++- 2 files changed, 54 insertions(+), 26 deletions(-) diff --git a/docs/doc_gen/dune b/docs/doc_gen/dune index e2f74a159f95..df502c1a1618 100644 --- a/docs/doc_gen/dune +++ b/docs/doc_gen/dune @@ -1,26 +1,31 @@ +; This file was automatically generated, do not edit. +; Edit file manifest/main.ml instead. + (executables - (names rpc_doc - p2p_doc) - (libraries octez-libs.base - octez-libs.rpc - octez-libs.stdlib-unix - octez-shell-libs.shell - octez-libs.rpc-http-server - octez_node_config - octez-shell-libs.protocol-updater - ; TODO tezos/tezos#2170: adapt next line(s) - tezos-protocol-genesis.embedded-protocol - tezos-protocol-016-PtMumbai.embedded-protocol - tezos-protocol-017-PtNairob.embedded-protocol - tezos-protocol-018-Proxford.embedded-protocol - tezos-protocol-alpha.embedded-protocol - data-encoding - re) - (flags (:standard -open Tezos_base__TzPervasives - -open Tezos_stdlib_unix - -open Tezos_shell - -open Tezos_store - -open Tezos_protocol_updater - -open Octez_node_config - -linkall - (:include %{workspace_root}/macos-link-flags.sexp)))) + (names rpc_doc p2p_doc) + (libraries + octez-libs.base + octez-libs.rpc + octez-libs.stdlib-unix + octez-shell-libs.shell + octez-libs.rpc-http-server + octez-shell-libs.store + octez-shell-libs.protocol-updater + octez-node-config + data-encoding + re + tezos-protocol-genesis.embedded-protocol + tezos-protocol-017-PtNairob.embedded-protocol + tezos-protocol-018-Proxford.embedded-protocol + tezos-protocol-alpha.embedded-protocol) + (link_flags + (:standard) + (:include %{workspace_root}/macos-link-flags.sexp)) + (flags + (:standard) + -open Tezos_base.TzPervasives + -open Tezos_stdlib_unix + -open Tezos_shell + -open Tezos_store + -open Tezos_protocol_updater + -open Octez_node_config)) diff --git a/manifest/main.ml b/manifest/main.ml index 96d223f3a6ea..fddf13be7a19 100644 --- a/manifest/main.ml +++ b/manifest/main.ml @@ -8480,6 +8480,29 @@ let _tezt_vesting_contract_test = ptime; ] +let _docs_doc_gen = + private_exes + ["rpc_doc"; "p2p_doc"] + ~opam:"" + ~path:"docs/doc_gen" + ~bisect_ppx:No + ~with_macos_security_framework:true + ~release_status:Unreleased + ~deps: + ([ + octez_base |> open_ ~m:"TzPervasives"; + octez_rpc; + octez_stdlib_unix |> open_; + octez_shell |> open_; + octez_rpc_http_server; + octez_store |> open_; + octez_protocol_updater |> open_; + octez_node_config |> open_; + data_encoding; + re; + ] + @ List.map Protocol.embedded (Protocol.genesis :: Protocol.active)) + (* Add entries to this function to declare that some dune and .opam files are not generated by the manifest on purpose. @@ -8509,7 +8532,7 @@ let exclude filename = (* The following directories do not contain packages that we release on opam. *) | "vendors" :: _ -> true | "scripts" :: _ -> true - | "docs" :: _ -> true + | "docs" :: "doc_gen" :: "errors" :: _ -> true (* opam/mandatory-for-make.opam is a trick to have [make build-deps] install some optional dependencies in a mandatory way. Once we use lock files, we can remove this, probably. *) -- GitLab From 11a0600b60c35d35729a47c1a8926ffd336897ba Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 2 Oct 2023 15:29:25 +0200 Subject: [PATCH 2/3] Manifest: generate [docs/doc_gen/errors/dune] --- docs/doc_gen/errors/dune | 28 ++++++++++++++++++---------- manifest/main.ml | 18 +++++++++++++++++- 2 files changed, 35 insertions(+), 11 deletions(-) diff --git a/docs/doc_gen/errors/dune b/docs/doc_gen/errors/dune index ede62d58af15..14115d7c6937 100644 --- a/docs/doc_gen/errors/dune +++ b/docs/doc_gen/errors/dune @@ -1,12 +1,20 @@ +; This file was automatically generated, do not edit. +; Edit file manifest/main.ml instead. + (executable (name error_doc) - (libraries data-encoding - octez-shell-libs.shell - octez-protocol-alpha-libs.client) - (flags (:standard -open Tezos_base - -open Tezos_error_monad - -open Data_encoding - -open Tezos_client_alpha - -safe-string - -linkall - (:include %{workspace_root}/macos-link-flags.sexp)))) + (libraries + octez-libs.base + octez-libs.error-monad + data-encoding + octez-protocol-alpha-libs.client) + (link_flags + (:standard) + (:include %{workspace_root}/macos-link-flags.sexp) + (-linkall)) + (flags + (:standard) + -open Tezos_base + -open Tezos_error_monad + -open Data_encoding + -open Tezos_client_alpha)) diff --git a/manifest/main.ml b/manifest/main.ml index fddf13be7a19..de31f797a10b 100644 --- a/manifest/main.ml +++ b/manifest/main.ml @@ -8503,6 +8503,23 @@ let _docs_doc_gen = ] @ List.map Protocol.embedded (Protocol.genesis :: Protocol.active)) +let _docs_doc_gen_errors = + private_exe + "error_doc" + ~opam:"" + ~path:"docs/doc_gen/errors" + ~bisect_ppx:No + ~with_macos_security_framework:true + ~release_status:Unreleased + ~linkall:true + ~deps: + [ + octez_base |> open_; + octez_error_monad |> open_; + data_encoding |> open_; + Protocol.(client_exn alpha) |> open_; + ] + (* Add entries to this function to declare that some dune and .opam files are not generated by the manifest on purpose. @@ -8532,7 +8549,6 @@ let exclude filename = (* The following directories do not contain packages that we release on opam. *) | "vendors" :: _ -> true | "scripts" :: _ -> true - | "docs" :: "doc_gen" :: "errors" :: _ -> true (* opam/mandatory-for-make.opam is a trick to have [make build-deps] install some optional dependencies in a mandatory way. Once we use lock files, we can remove this, probably. *) -- GitLab From c0094aa2205a3b792823ee9bb9ac84fbb2eff23d Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Wed, 4 Oct 2023 17:25:42 +0200 Subject: [PATCH 3/3] [doc_gen/rpc_doc.ml]: parameterize by protocol hash Refactor the [doc_gen/rpc_doc.exe] binary so that instead of keeping a list of protocols for which we can generate the protocol, the binary takes a protocol name (e.g. "alpha") and hash as argument. --- docs/Makefile | 5 +- docs/doc_gen/rpc_doc.ml | 136 +++++++++++++++++----------------------- 2 files changed, 62 insertions(+), 79 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 75689781bd29..08655c24bc9c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -147,8 +147,11 @@ $(P2PDOCEXE): docexes api/errors.rst: $(ERRDOCEXE) $(ERRDOCEXE) > api/errors.rst +shell/rpc.rst: $(RPCDOCEXE) + $(RPCDOCEXE) index shell /shell/rpc_introduction.rst.inc > $@ + %/rpc.rst: $(RPCDOCEXE) - $(RPCDOCEXE) index $(@D) > $@ + $(RPCDOCEXE) index $(@D) $($(@D)_long) /include/rpc_introduction.rst.inc > $@ user/default-acl.json: $(RPCDOCEXE) $(RPCDOCEXE) acl > $@ diff --git a/docs/doc_gen/rpc_doc.ml b/docs/doc_gen/rpc_doc.ml index 26420d381293..e354f25604d7 100644 --- a/docs/doc_gen/rpc_doc.ml +++ b/docs/doc_gen/rpc_doc.ml @@ -23,30 +23,6 @@ (* *) (*****************************************************************************) -let protocols = - (* version, title that appears in the doc, an optional path to an introduction, protocol hash *) - (* the optional introduction is inserted between the title "RPCs index" - and the generated directory description *) - [ - ( "alpha", - "Alpha", - Some "/include/rpc_introduction.rst.inc", - "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" ); - (* TODO tezos/tezos#2170: adapt rest of this list *) - ( "mumbai", - "Mumbai", - Some "/include/rpc_introduction.rst.inc", - "PtMumbai2TmsJHNGRkD8v8YDbtao7BLUC3wjASn1inAKLFCjaH1" ); - ( "nairobi", - "Nairobi", - Some "/include/rpc_introduction.rst.inc", - "PtNairobiyssHuh87hEhfVBGCVrK3WnS8Z2FT4ymB5tAa4r1nQf" ); - ( "oxford", - "Oxford", - Some "/include/rpc_introduction.rst.inc", - "ProxfordSW2S7fvchT1Zgj2avb5UES194neRyYVXoaDGvF9egt8" ); - ] - let pp_name ppf = function | [] | [""] -> Format.pp_print_string ppf "/" | prefix -> Format.pp_print_string ppf (String.concat "/" prefix) @@ -374,59 +350,54 @@ let pp_document ppf _name intro prefix rpc_dir version = Format.pp_set_max_indent ppf 76 ; Format.fprintf ppf "%a@\n@\n" (Description.pp prefix) rpc_dir -let make_index node required_version = +let make_index_shell ?introduction_path node = let open Lwt_syntax in - let version = Tezos_version_value.Current_git_info.version in - let commit_info = - ({ - commit_hash = Tezos_version_value.Current_git_info.commit_hash; - commit_date = Tezos_version_value.Current_git_info.committer_date; - } - : Tezos_version.Node_version.commit_info) - in - let shell_dir = Node.build_rpc_directory ~version ~commit_info node in - let shell_dir = - Tezos_rpc.Directory.register0 shell_dir Node_services.S.config (fun () () -> - Lwt.return_ok Config_file.default_config) - in - let protocol_dirs = - List.map - (fun (version, name, intro, hash) -> - let hash = Protocol_hash.of_b58check_exn hash in - let (module Proto) = - match Registered_protocol.get hash with - | None -> - (* This is probably an indication that a line for the - requested protocol is missing in the dune file of - this repository *) - Format.eprintf "Hash not found: %a" Protocol_hash.pp hash ; - assert false - | Some proto -> proto - in - ( version, - "Protocol " ^ name, - intro, - [".."; ""], - Tezos_rpc.Directory.map (fun () -> assert false) - @@ Block_directory.build_raw_rpc_directory - (module Proto) - (module Proto) )) - protocols - in - let dirs = - ("shell", "Shell", Some "/shell/rpc_introduction.rst.inc", [""], shell_dir) - :: protocol_dirs + let* shell_dir = + let version = Tezos_version_value.Current_git_info.version in + let commit_info = + ({ + commit_hash = Tezos_version_value.Current_git_info.commit_hash; + commit_date = Tezos_version_value.Current_git_info.committer_date; + } + : Tezos_version.Node_version.commit_info) + in + let shell_dir = Node.build_rpc_directory ~version ~commit_info node in + let shell_dir = + Tezos_rpc.Directory.register0 + shell_dir + Node_services.S.config + (fun () () -> Lwt.return_ok Config_file.default_config) + in + Tezos_rpc.Directory.describe_directory ~recurse:true ~arg:() shell_dir in - let _version, name, intro, path, dir = - WithExceptions.Option.get ~loc:__LOC__ - @@ List.find - (fun (version, _name, _intro, _path, _dir) -> - version = required_version) - dirs + let ppf = Format.std_formatter in + pp_document ppf "Shell" introduction_path [""] shell_dir "shell" ; + return_ok () + +let make_index ?introduction_path ~required_version ~hash () = + let open Lwt_syntax in + let name = "Protocol " ^ String.capitalize_ascii required_version in + let path = [".."; ""] in + let* dir = + let dir = + let hash = Protocol_hash.of_b58check_exn hash in + let (module Proto) = + match Registered_protocol.get hash with + | None -> + (* This is probably an indication that a line for the + requested protocol is missing in the dune file of + this repository *) + Format.eprintf "Hash not found: %a" Protocol_hash.pp hash ; + assert false + | Some proto -> proto + in + Tezos_rpc.Directory.map (fun () -> assert false) + @@ Block_directory.build_raw_rpc_directory (module Proto) (module Proto) + in + Tezos_rpc.Directory.describe_directory ~recurse:true ~arg:() dir in - let* dir = Tezos_rpc.Directory.describe_directory ~recurse:true ~arg:() dir in let ppf = Format.std_formatter in - pp_document ppf name intro path dir required_version ; + pp_document ppf name introduction_path path dir required_version ; return_ok () let make_default_acl _node = @@ -441,10 +412,19 @@ let make_default_acl _node = Lwt.return_ok () let main node = - let cmd = Sys.argv.(1) in - match cmd with - | "index" -> make_index node Sys.argv.(2) - | "acl" -> make_default_acl node - | _ -> raise (Invalid_argument cmd) + match Sys.argv |> Array.to_list with + | [_; "acl"] -> make_default_acl node + | [_; "index"; "shell"] -> make_index_shell node + | [_; "index"; "shell"; introduction_path] -> + make_index_shell ~introduction_path node + | [_; "index"; required_version; hash] -> + make_index ~required_version ~hash () + | [_; "index"; required_version; hash; introduction_path] -> + make_index ~required_version ~hash ~introduction_path () + | _ -> + raise + (Invalid_argument + "Unrecognized arguments: must be either 'acl' or 'index \ + []") let () = Lwt_main.run (Node_helpers.with_node main) -- GitLab