From 05194132b9ef68bd6a4f006ae59785ea74dac0c8 Mon Sep 17 00:00:00 2001 From: Killian Delarue Date: Thu, 6 Jul 2023 15:26:06 +0200 Subject: [PATCH 1/5] Manifest: Add synopsis to octez-libs --- manifest/main.ml | 3 ++- opam/octez-libs.opam | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/manifest/main.ml b/manifest/main.ml index ddce5a12075a..30924d52c57b 100644 --- a/manifest/main.ml +++ b/manifest/main.ml @@ -497,7 +497,8 @@ let octez_lib ?internal_name ?js_of_ocaml ?inline_tests ?foreign_stubs ("octez-libs." ^ public_name) ~internal_name:name ~opam:"octez-libs" - ~synopsis:"Octez libs" + ~synopsis: + "A package that contains multiple base libraries used by the Octez suite" ?opam_with_test ?linkall ?js_compatible diff --git a/opam/octez-libs.opam b/opam/octez-libs.opam index 2295a2b635fc..308ec443115d 100644 --- a/opam/octez-libs.opam +++ b/opam/octez-libs.opam @@ -87,4 +87,4 @@ build: [ ["dune" "build" "-p" name "-j" jobs] ["dune" "runtest" "-p" name "-j" jobs] {with-test} ] -synopsis: "Octez libs" +synopsis: "A package that contains multiple base libraries used by the Octez suite" -- GitLab From c43be2627e5e9a086bd86aaf1ab569a9968f2fb1 Mon Sep 17 00:00:00 2001 From: Killian Delarue Date: Thu, 6 Jul 2023 15:26:27 +0200 Subject: [PATCH 2/5] Manifest: Allow description to octez-libs sublibs --- manifest/main.ml | 59 ++++++++++++++++++++++++------------------ src/lib_base/index.mld | 58 ++++++++++++++++++++--------------------- 2 files changed, 63 insertions(+), 54 deletions(-) diff --git a/manifest/main.ml b/manifest/main.ml index 30924d52c57b..fdc46d571da1 100644 --- a/manifest/main.ml +++ b/manifest/main.ml @@ -457,10 +457,16 @@ let alcotezt = ~deps:[tezt_core_lib] |> open_ -type sub_lib_documentation_link = Module of string | Page of string +type sub_lib_documentation_entrypoint = Module | Page + +type sub_lib = { + name : string; + synopsis : string option; + documentation_type : sub_lib_documentation_entrypoint; +} (* List of the registered sublibraries of octez-libs *) -let registered_octez_libs : sub_lib_documentation_link list ref = ref [] +let registered_octez_libs : sub_lib list ref = ref [] (* Registers [public_name] as a sublibrary of the [octez-libs] package. @@ -471,7 +477,7 @@ let registered_octez_libs : sub_lib_documentation_link list ref = ref [] let octez_lib ?internal_name ?js_of_ocaml ?inline_tests ?foreign_stubs ?documentation ?conflicts ?flags ?time_measurement_ppx ?deps ?dune ?modules ?linkall ?js_compatible ?bisect_ppx ?preprocess ?opam_only_deps ?cram - ?release_status ?ctypes ?opam_with_test ?c_library_flags ?synopsis:_ ~path + ?release_status ?ctypes ?c_library_flags ?opam_with_test ?synopsis ~path public_name = let name = let s = Option.value ~default:public_name internal_name in @@ -485,12 +491,15 @@ let octez_lib ?internal_name ?js_of_ocaml ?inline_tests ?foreign_stubs in let registered = match documentation with - | None -> Module (String.capitalize_ascii name) - | Some (docs : Dune.s_expr) when docs = [Dune.[S "package"; S "octez-libs"]] - -> - (* In that specific case, we don't want the page to be used *) - Module (String.capitalize_ascii name) - | Some _docs -> Page name + | None | Some Dune.[[S "package"; S "octez-libs"]] -> + (* In the case that the documentation stanza is only a package declaration, + we don't want the page to be used *) + { + name = String.capitalize_ascii name; + synopsis; + documentation_type = Module; + } + | Some _docs -> {name; synopsis; documentation_type = Page} in registered_octez_libs := registered :: !registered_octez_libs ; public_lib @@ -531,19 +540,24 @@ let octez_lib ?internal_name ?js_of_ocaml ?inline_tests ?foreign_stubs (* Prints all the registered octez libraries as a documentation index *) let pp_octez_libs_index fmt registered_octez_libs = let header = - "{0 Octez-libs: octez libraries}\n\n\ + "{0 Octez-libs: Octez libraries}\n\n\ This is a package containing some libraries used by the Octez project.\n\n\ It contains the following libraries:\n\n" in let pp_registered pp = function - | Module registered -> - Format.fprintf pp "- {{!module-%s}%s}" registered registered - | Page registered -> + | {name; synopsis = None; documentation_type = Module} -> + Format.fprintf pp "- {{!module-%s}%s}" name name + | {name; synopsis = Some synopsis; documentation_type = Module} -> + Format.fprintf pp "- {{!module-%s}%s}: %s" name name synopsis + | {name; synopsis = None; documentation_type = Page} -> + Format.fprintf pp "- {{!page-%s}%s}" name (String.capitalize_ascii name) + | {name; synopsis = Some synopsis; documentation_type = Page} -> Format.fprintf pp - "- {{!page-%s}%s}" - registered - (String.capitalize_ascii registered) + "- {{!page-%s}%s}: %s" + name + (String.capitalize_ascii name) + synopsis in Format.fprintf fmt @@ -553,15 +567,10 @@ let pp_octez_libs_index fmt registered_octez_libs = ~pp_sep:(fun pp () -> Format.fprintf pp "@.") pp_registered) @@ List.sort - (fun lib1 lib2 -> - match (lib1, lib2) with - | Page n1, Page n2 - | Page n1, Module n2 - | Module n1, Page n2 - | Module n1, Module n2 -> - String.compare - (String.capitalize_ascii n1) - (String.capitalize_ascii n2)) + (fun {name = name1; _} {name = name2; _} -> + String.compare + (String.capitalize_ascii name1) + (String.capitalize_ascii name2)) registered_octez_libs let octez_test_helpers = diff --git a/src/lib_base/index.mld b/src/lib_base/index.mld index 71f0f38e75ae..3c85502c7156 100644 --- a/src/lib_base/index.mld +++ b/src/lib_base/index.mld @@ -1,4 +1,4 @@ -{0 Octez-libs: octez libraries} +{0 Octez-libs: Octez libraries} This is a package containing some libraries used by the Octez project. @@ -16,19 +16,19 @@ It contains the following libraries: - {{!module-Distribution}Distribution} - {{!module-Epoxy_tx}Epoxy_tx} - {{!module-Mec}Mec} -- {{!module-Octez_bls12_381_polynomial}Octez_bls12_381_polynomial} +- {{!module-Octez_bls12_381_polynomial}Octez_bls12_381_polynomial}: Polynomials over BLS12-381 finite field - Temporary vendored version of Octez - {{!module-Octez_srs_extraction}Octez_srs_extraction} - {{!module-Plompiler}Plompiler} - {{!module-Plonk}Plonk} - {{!module-Plonk_test}Plonk_test} -- {{!module-Polynomial}Polynomial} -- {{!module-Tezos_base}Tezos_base} +- {{!module-Polynomial}Polynomial}: Polynomials over finite fields +- {{!module-Tezos_base}Tezos_base}: Tezos: meta-package and pervasive type definitions for Tezos - {{!module-Tezos_base_p2p_identity_file}Tezos_base_p2p_identity_file} -- {{!module-Tezos_base_test_helpers}Tezos_base_test_helpers} +- {{!module-Tezos_base_test_helpers}Tezos_base_test_helpers}: Tezos: Tezos base test helpers - {{!module-Tezos_base_unix}Tezos_base_unix} - {{!module-Tezos_clic}Tezos_clic} - {{!module-Tezos_clic_unix}Tezos_clic_unix} -- {{!module-Tezos_context}Tezos_context} +- {{!module-Tezos_context}Tezos_context}: Tezos: on-disk context abstraction for `octez-node` - {{!module-Tezos_context_disk}Tezos_context_disk} - {{!module-Tezos_context_dump}Tezos_context_dump} - {{!module-Tezos_context_encoding}Tezos_context_encoding} @@ -36,45 +36,45 @@ It contains the following libraries: - {{!module-Tezos_context_memory}Tezos_context_memory} - {{!module-Tezos_context_merkle_proof_encoding}Tezos_context_merkle_proof_encoding} - {{!module-Tezos_context_sigs}Tezos_context_sigs} -- {{!module-Tezos_crypto}Tezos_crypto} -- {{!module-Tezos_crypto_dal}Tezos_crypto_dal} +- {{!module-Tezos_crypto}Tezos_crypto}: Tezos: library with all the cryptographic primitives used by Tezos +- {{!module-Tezos_crypto_dal}Tezos_crypto_dal}: DAL cryptographic primitives - {{!module-Tezos_crypto_dal_octez_dal_config}Tezos_crypto_dal_octez_dal_config} -- {{!module-Tezos_error_monad}Tezos_error_monad} -- {{!module-Tezos_event_logging}Tezos_event_logging} -- {{!module-Tezos_event_logging_test_helpers}Tezos_event_logging_test_helpers} +- {{!module-Tezos_error_monad}Tezos_error_monad}: Tezos: error monad +- {{!module-Tezos_event_logging}Tezos_event_logging}: Tezos event logging library +- {{!module-Tezos_event_logging_test_helpers}Tezos_event_logging_test_helpers}: Tezos: test helpers for the event logging library - {{!module-Tezos_expect_helper}Tezos_expect_helper} - {{!module-Tezos_gossipsub}Tezos_gossipsub} -- {{!module-Tezos_hacl}Tezos_hacl} -- {{!module-Tezos_lazy_containers}Tezos_lazy_containers} -- {{!page-tezos_lwt_result_stdlib}Tezos_lwt_result_stdlib} -- {{!module-Tezos_micheline}Tezos_micheline} -- {{!module-Tezos_p2p}Tezos_p2p} -- {{!module-Tezos_p2p_services}Tezos_p2p_services} +- {{!module-Tezos_hacl}Tezos_hacl}: Tezos: thin layer around hacl-star +- {{!module-Tezos_lazy_containers}Tezos_lazy_containers}: A collection of lazy containers whose contents is fetched from arbitrary backend on-demand +- {{!page-tezos_lwt_result_stdlib}Tezos_lwt_result_stdlib}: Tezos: error-aware stdlib replacement +- {{!module-Tezos_micheline}Tezos_micheline}: Tezos: internal AST and parser for the Michelson language +- {{!module-Tezos_p2p}Tezos_p2p}: Tezos: library for a pool of P2P connections +- {{!module-Tezos_p2p_services}Tezos_p2p_services}: Tezos: descriptions of RPCs exported by `tezos-p2p` - {{!module-Tezos_p2p_test_common}Tezos_p2p_test_common} - {{!module-Tezos_protocol_environment}Tezos_protocol_environment} - {{!module-Tezos_protocol_environment_sigs}Tezos_protocol_environment_sigs} - {{!module-Tezos_protocol_environment_sigs_internals}Tezos_protocol_environment_sigs_internals} - {{!module-Tezos_protocol_environment_structs}Tezos_protocol_environment_structs} - {{!module-Tezos_requester}Tezos_requester} -- {{!module-Tezos_rpc}Tezos_rpc} -- {{!module-Tezos_rpc_http}Tezos_rpc_http} -- {{!module-Tezos_rpc_http_client}Tezos_rpc_http_client} -- {{!module-Tezos_rpc_http_client_unix}Tezos_rpc_http_client_unix} -- {{!module-Tezos_rpc_http_server}Tezos_rpc_http_server} +- {{!module-Tezos_rpc}Tezos_rpc}: Tezos: library of auto-documented RPCs (service and hierarchy descriptions) +- {{!module-Tezos_rpc_http}Tezos_rpc_http}: Tezos: library of auto-documented RPCs (http server and client) +- {{!module-Tezos_rpc_http_client}Tezos_rpc_http_client}: Tezos: library of auto-documented RPCs (http client) +- {{!module-Tezos_rpc_http_client_unix}Tezos_rpc_http_client_unix}: Tezos: unix implementation of the RPC client +- {{!module-Tezos_rpc_http_server}Tezos_rpc_http_server}: Tezos: library of auto-documented RPCs (http server) - {{!module-Tezos_sapling}Tezos_sapling} - {{!module-Tezos_scoru_wasm}Tezos_scoru_wasm} - {{!module-Tezos_shell_context}Tezos_shell_context} -- {{!module-Tezos_shell_services}Tezos_shell_services} -- {{!module-Tezos_stdlib}Tezos_stdlib} -- {{!module-Tezos_stdlib_unix}Tezos_stdlib_unix} +- {{!module-Tezos_shell_services}Tezos_shell_services}: Tezos: descriptions of RPCs exported by `tezos-shell` +- {{!module-Tezos_stdlib}Tezos_stdlib}: Tezos: yet-another local-extension of the OCaml standard library +- {{!module-Tezos_stdlib_unix}Tezos_stdlib_unix}: Tezos: yet-another local-extension of the OCaml standard library (unix-specific fragment) - {{!module-Tezos_test_helpers}Tezos_test_helpers} -- {{!module-Tezos_tree_encoding}Tezos_tree_encoding} -- {{!module-Tezos_version}Tezos_version} +- {{!module-Tezos_tree_encoding}Tezos_tree_encoding}: A general-purpose library to encode arbitrary data in Merkle trees +- {{!module-Tezos_version}Tezos_version}: Tezos: version information generated from Git - {{!module-Tezos_version_parser}Tezos_version_parser} - {{!module-Tezos_webassembly_interpreter}Tezos_webassembly_interpreter} -- {{!page-tezos_workers}Tezos_workers} +- {{!page-tezos_workers}Tezos_workers}: Tezos: worker library - {{!module-Tezt_performance_regression}Tezt_performance_regression} -- {{!module-Tezt_tezos}Tezt_tezos} +- {{!module-Tezt_tezos}Tezt_tezos}: Tezos test framework based on Tezt - {{!module-Traced_functor_outputs}Traced_functor_outputs} - {{!module-Traced_sigs}Traced_sigs} - {{!module-Traced_structs}Traced_structs} -- GitLab From a4209db5e1629e7ff5d260d6858ef708396fd8f6 Mon Sep 17 00:00:00 2001 From: Killian Delarue Date: Wed, 2 Aug 2023 14:54:05 +0200 Subject: [PATCH 3/5] Manifest: Update synopsis of octez-libs sublibs --- manifest/main.ml | 48 ++++++++++++++++++++---------------------- src/lib_base/index.mld | 46 ++++++++++++++++++++-------------------- 2 files changed, 46 insertions(+), 48 deletions(-) diff --git a/manifest/main.ml b/manifest/main.ml index fdc46d571da1..38122160764f 100644 --- a/manifest/main.ml +++ b/manifest/main.ml @@ -605,7 +605,7 @@ let octez_stdlib = octez_lib "tezos-stdlib" ~path:"src/lib_stdlib" - ~synopsis:"Tezos: yet-another local-extension of the OCaml standard library" + ~synopsis:"Yet-another local-extension of the OCaml standard library" ~deps:[hex; zarith; zarith_stubs_js; lwt; aches] ~js_compatible:true ~js_of_ocaml: @@ -724,7 +724,7 @@ let octez_lwt_result_stdlib = octez_lib "tezos-lwt-result-stdlib" ~path:"src/lib_lwt_result_stdlib" - ~synopsis:"Tezos: error-aware stdlib replacement" + ~synopsis:"error-aware stdlib replacement" ~js_compatible:true ~documentation: Dune. @@ -785,7 +785,7 @@ let octez_error_monad = octez_lib "tezos-error-monad" ~path:"src/lib_error_monad" - ~synopsis:"Tezos: error monad" + ~synopsis:"Error monad" ~deps: [ octez_stdlib |> open_; @@ -804,7 +804,7 @@ let octez_hacl = octez_lib "tezos-hacl" ~path:"src/lib_hacl" - ~synopsis:"Tezos: thin layer around hacl-star" + ~synopsis:"Thin layer around hacl-star" ~deps:[hacl_star; hacl_star_raw; ctypes_stubs_js] ~js_of_ocaml: [ @@ -941,8 +941,7 @@ let octez_rpc = "tezos-rpc" ~path:"src/lib_rpc" ~synopsis: - "Tezos: library of auto-documented RPCs (service and hierarchy \ - descriptions)" + "Library of auto-documented RPCs (service and hierarchy descriptions)" ~deps: [ data_encoding |> open_; @@ -1233,8 +1232,7 @@ let octez_crypto = octez_lib "tezos-crypto" ~path:"src/lib_crypto" - ~synopsis: - "Tezos: library with all the cryptographic primitives used by Tezos" + ~synopsis:"Library with all the cryptographic primitives used by Tezos" ~deps: [ octez_stdlib |> open_; @@ -1920,7 +1918,7 @@ let octez_event_logging = octez_lib "tezos-event-logging" ~path:"src/lib_event_logging" - ~synopsis:"Tezos event logging library" + ~synopsis:"Octez event logging library" ~deps: [ octez_stdlib |> open_; @@ -1935,7 +1933,7 @@ let octez_event_logging_test_helpers = octez_lib "tezos-event-logging-test-helpers" ~path:"src/lib_event_logging/test_helpers" - ~synopsis:"Tezos: test helpers for the event logging library" + ~synopsis:"Test helpers for the event logging library" ~deps: [ octez_stdlib; @@ -1955,7 +1953,7 @@ let octez_stdlib_unix = "tezos-stdlib-unix" ~path:"src/lib_stdlib_unix" ~synopsis: - "Tezos: yet-another local-extension of the OCaml standard library \ + "Yet-another local-extension of the OCaml standard library \ (unix-specific fragment)" ~deps: [ @@ -2040,7 +2038,7 @@ let octez_micheline = octez_lib "tezos-micheline" ~path:"src/lib_micheline" - ~synopsis:"Tezos: internal AST and parser for the Michelson language" + ~synopsis:"Internal AST and parser for the Michelson language" ~deps: [ uutf; @@ -2077,7 +2075,7 @@ let octez_base = octez_lib "tezos-base" ~path:"src/lib_base" - ~synopsis:"Tezos: meta-package and pervasive type definitions for Tezos" + ~synopsis:"Meta-package and pervasive type definitions for Tezos" ~deps: [ octez_stdlib |> open_; @@ -2176,7 +2174,7 @@ let octez_base_test_helpers = octez_lib "tezos-base-test-helpers" ~path:"src/lib_base/test_helpers" - ~synopsis:"Tezos: Tezos base test helpers" + ~synopsis:"Octez base test helpers" ~deps: [ octez_base |> open_ ~m:"TzPervasives"; @@ -2302,7 +2300,7 @@ let octez_version = octez_lib "tezos-version" ~path:"src/lib_version" - ~synopsis:"Tezos: version information generated from Git" + ~synopsis:"Version information generated from Git" ~deps:[octez_base |> open_ ~m:"TzPervasives"; octez_version_parser] ~js_compatible:true @@ -2365,7 +2363,7 @@ let octez_p2p_services = octez_lib "tezos-p2p-services" ~path:"src/lib_p2p_services" - ~synopsis:"Tezos: descriptions of RPCs exported by `tezos-p2p`" + ~synopsis:"Descriptions of RPCs exported by [tezos-p2p]" ~deps:[octez_base |> open_ ~m:"TzPervasives"; octez_rpc] ~linkall:true ~js_compatible:true @@ -2374,7 +2372,7 @@ let octez_workers = octez_lib "tezos-workers" ~path:"src/lib_workers" - ~synopsis:"Tezos: worker library" + ~synopsis:"Worker library" ~documentation: Dune.[[S "package"; S "octez-libs"]; [S "mld_files"; S "tezos_workers"]] ~deps: @@ -2416,7 +2414,7 @@ let octez_shell_services = octez_lib "tezos-shell-services" ~path:"src/lib_shell_services" - ~synopsis:"Tezos: descriptions of RPCs exported by `tezos-shell`" + ~synopsis:"Descriptions of RPCs exported by [tezos-shell]" ~deps: [ octez_base |> open_ ~m:"TzPervasives" |> open_; @@ -2479,7 +2477,7 @@ let octez_p2p = octez_lib "tezos-p2p" ~path:"src/lib_p2p" - ~synopsis:"Tezos: library for a pool of P2P connections" + ~synopsis:"Library for a pool of P2P connections" ~deps: [ lwt_watcher; @@ -2507,7 +2505,7 @@ let tezt_tezos = octez_lib "tezt-tezos" ~path:"tezt/lib_tezos" - ~synopsis:"Tezos test framework based on Tezt" + ~synopsis:"Octez test framework based on Tezt" ~bisect_ppx:No ~deps: [ @@ -2807,7 +2805,7 @@ let octez_context = octez_lib "tezos-context" ~path:"src/lib_context" - ~synopsis:"Tezos: on-disk context abstraction for `octez-node`" + ~synopsis:"On-disk context abstraction for [octez-node]" ~deps:[octez_context_disk; octez_context_memory] let _octez_context_tests = @@ -3502,7 +3500,7 @@ let octez_rpc_http = octez_lib "tezos-rpc-http" ~path:"src/lib_rpc_http" - ~synopsis:"Tezos: library of auto-documented RPCs (http server and client)" + ~synopsis:"Library of auto-documented RPCs (http server and client)" ~deps:[octez_base |> open_ ~m:"TzPervasives"; octez_rpc; resto_cohttp; uri] ~modules:["RPC_client_errors"; "media_type"] @@ -3510,7 +3508,7 @@ let octez_rpc_http_client = octez_lib "tezos-rpc-http-client" ~path:"src/lib_rpc_http" - ~synopsis:"Tezos: library of auto-documented RPCs (http client)" + ~synopsis:"Library of auto-documented RPCs (http client)" ~deps: [ octez_base |> open_ ~m:"TzPervasives"; @@ -3524,7 +3522,7 @@ let octez_rpc_http_client_unix = octez_lib "tezos-rpc-http-client-unix" ~path:"src/lib_rpc_http" - ~synopsis:"Tezos: unix implementation of the RPC client" + ~synopsis:"Unix implementation of the RPC client" ~deps: [ octez_stdlib_unix; @@ -3540,7 +3538,7 @@ let octez_rpc_http_server = octez_lib "tezos-rpc-http-server" ~path:"src/lib_rpc_http" - ~synopsis:"Tezos: library of auto-documented RPCs (http server)" + ~synopsis:"Library of auto-documented RPCs (http server)" ~deps: [ octez_base |> open_ ~m:"TzPervasives"; diff --git a/src/lib_base/index.mld b/src/lib_base/index.mld index 3c85502c7156..6b2037463418 100644 --- a/src/lib_base/index.mld +++ b/src/lib_base/index.mld @@ -22,13 +22,13 @@ It contains the following libraries: - {{!module-Plonk}Plonk} - {{!module-Plonk_test}Plonk_test} - {{!module-Polynomial}Polynomial}: Polynomials over finite fields -- {{!module-Tezos_base}Tezos_base}: Tezos: meta-package and pervasive type definitions for Tezos +- {{!module-Tezos_base}Tezos_base}: Meta-package and pervasive type definitions for Tezos - {{!module-Tezos_base_p2p_identity_file}Tezos_base_p2p_identity_file} -- {{!module-Tezos_base_test_helpers}Tezos_base_test_helpers}: Tezos: Tezos base test helpers +- {{!module-Tezos_base_test_helpers}Tezos_base_test_helpers}: Octez base test helpers - {{!module-Tezos_base_unix}Tezos_base_unix} - {{!module-Tezos_clic}Tezos_clic} - {{!module-Tezos_clic_unix}Tezos_clic_unix} -- {{!module-Tezos_context}Tezos_context}: Tezos: on-disk context abstraction for `octez-node` +- {{!module-Tezos_context}Tezos_context}: On-disk context abstraction for [octez-node] - {{!module-Tezos_context_disk}Tezos_context_disk} - {{!module-Tezos_context_dump}Tezos_context_dump} - {{!module-Tezos_context_encoding}Tezos_context_encoding} @@ -36,45 +36,45 @@ It contains the following libraries: - {{!module-Tezos_context_memory}Tezos_context_memory} - {{!module-Tezos_context_merkle_proof_encoding}Tezos_context_merkle_proof_encoding} - {{!module-Tezos_context_sigs}Tezos_context_sigs} -- {{!module-Tezos_crypto}Tezos_crypto}: Tezos: library with all the cryptographic primitives used by Tezos +- {{!module-Tezos_crypto}Tezos_crypto}: Library with all the cryptographic primitives used by Tezos - {{!module-Tezos_crypto_dal}Tezos_crypto_dal}: DAL cryptographic primitives - {{!module-Tezos_crypto_dal_octez_dal_config}Tezos_crypto_dal_octez_dal_config} -- {{!module-Tezos_error_monad}Tezos_error_monad}: Tezos: error monad -- {{!module-Tezos_event_logging}Tezos_event_logging}: Tezos event logging library -- {{!module-Tezos_event_logging_test_helpers}Tezos_event_logging_test_helpers}: Tezos: test helpers for the event logging library +- {{!module-Tezos_error_monad}Tezos_error_monad}: Error monad +- {{!module-Tezos_event_logging}Tezos_event_logging}: Octez event logging library +- {{!module-Tezos_event_logging_test_helpers}Tezos_event_logging_test_helpers}: Test helpers for the event logging library - {{!module-Tezos_expect_helper}Tezos_expect_helper} - {{!module-Tezos_gossipsub}Tezos_gossipsub} -- {{!module-Tezos_hacl}Tezos_hacl}: Tezos: thin layer around hacl-star +- {{!module-Tezos_hacl}Tezos_hacl}: Thin layer around hacl-star - {{!module-Tezos_lazy_containers}Tezos_lazy_containers}: A collection of lazy containers whose contents is fetched from arbitrary backend on-demand -- {{!page-tezos_lwt_result_stdlib}Tezos_lwt_result_stdlib}: Tezos: error-aware stdlib replacement -- {{!module-Tezos_micheline}Tezos_micheline}: Tezos: internal AST and parser for the Michelson language -- {{!module-Tezos_p2p}Tezos_p2p}: Tezos: library for a pool of P2P connections -- {{!module-Tezos_p2p_services}Tezos_p2p_services}: Tezos: descriptions of RPCs exported by `tezos-p2p` +- {{!page-tezos_lwt_result_stdlib}Tezos_lwt_result_stdlib}: error-aware stdlib replacement +- {{!module-Tezos_micheline}Tezos_micheline}: Internal AST and parser for the Michelson language +- {{!module-Tezos_p2p}Tezos_p2p}: Library for a pool of P2P connections +- {{!module-Tezos_p2p_services}Tezos_p2p_services}: Descriptions of RPCs exported by [tezos-p2p] - {{!module-Tezos_p2p_test_common}Tezos_p2p_test_common} - {{!module-Tezos_protocol_environment}Tezos_protocol_environment} - {{!module-Tezos_protocol_environment_sigs}Tezos_protocol_environment_sigs} - {{!module-Tezos_protocol_environment_sigs_internals}Tezos_protocol_environment_sigs_internals} - {{!module-Tezos_protocol_environment_structs}Tezos_protocol_environment_structs} - {{!module-Tezos_requester}Tezos_requester} -- {{!module-Tezos_rpc}Tezos_rpc}: Tezos: library of auto-documented RPCs (service and hierarchy descriptions) -- {{!module-Tezos_rpc_http}Tezos_rpc_http}: Tezos: library of auto-documented RPCs (http server and client) -- {{!module-Tezos_rpc_http_client}Tezos_rpc_http_client}: Tezos: library of auto-documented RPCs (http client) -- {{!module-Tezos_rpc_http_client_unix}Tezos_rpc_http_client_unix}: Tezos: unix implementation of the RPC client -- {{!module-Tezos_rpc_http_server}Tezos_rpc_http_server}: Tezos: library of auto-documented RPCs (http server) +- {{!module-Tezos_rpc}Tezos_rpc}: Library of auto-documented RPCs (service and hierarchy descriptions) +- {{!module-Tezos_rpc_http}Tezos_rpc_http}: Library of auto-documented RPCs (http server and client) +- {{!module-Tezos_rpc_http_client}Tezos_rpc_http_client}: Library of auto-documented RPCs (http client) +- {{!module-Tezos_rpc_http_client_unix}Tezos_rpc_http_client_unix}: Unix implementation of the RPC client +- {{!module-Tezos_rpc_http_server}Tezos_rpc_http_server}: Library of auto-documented RPCs (http server) - {{!module-Tezos_sapling}Tezos_sapling} - {{!module-Tezos_scoru_wasm}Tezos_scoru_wasm} - {{!module-Tezos_shell_context}Tezos_shell_context} -- {{!module-Tezos_shell_services}Tezos_shell_services}: Tezos: descriptions of RPCs exported by `tezos-shell` -- {{!module-Tezos_stdlib}Tezos_stdlib}: Tezos: yet-another local-extension of the OCaml standard library -- {{!module-Tezos_stdlib_unix}Tezos_stdlib_unix}: Tezos: yet-another local-extension of the OCaml standard library (unix-specific fragment) +- {{!module-Tezos_shell_services}Tezos_shell_services}: Descriptions of RPCs exported by [tezos-shell] +- {{!module-Tezos_stdlib}Tezos_stdlib}: Yet-another local-extension of the OCaml standard library +- {{!module-Tezos_stdlib_unix}Tezos_stdlib_unix}: Yet-another local-extension of the OCaml standard library (unix-specific fragment) - {{!module-Tezos_test_helpers}Tezos_test_helpers} - {{!module-Tezos_tree_encoding}Tezos_tree_encoding}: A general-purpose library to encode arbitrary data in Merkle trees -- {{!module-Tezos_version}Tezos_version}: Tezos: version information generated from Git +- {{!module-Tezos_version}Tezos_version}: Version information generated from Git - {{!module-Tezos_version_parser}Tezos_version_parser} - {{!module-Tezos_webassembly_interpreter}Tezos_webassembly_interpreter} -- {{!page-tezos_workers}Tezos_workers}: Tezos: worker library +- {{!page-tezos_workers}Tezos_workers}: Worker library - {{!module-Tezt_performance_regression}Tezt_performance_regression} -- {{!module-Tezt_tezos}Tezt_tezos}: Tezos test framework based on Tezt +- {{!module-Tezt_tezos}Tezt_tezos}: Octez test framework based on Tezt - {{!module-Traced_functor_outputs}Traced_functor_outputs} - {{!module-Traced_sigs}Traced_sigs} - {{!module-Traced_structs}Traced_structs} -- GitLab From fde620f99e58d8e9578816ca1744b3fa2ec261b6 Mon Sep 17 00:00:00 2001 From: Killian Delarue Date: Thu, 3 Aug 2023 14:17:35 +0200 Subject: [PATCH 4/5] Manifest: Remove sub-libs links in octez-libs doc --- manifest/main.ml | 36 +++++++++++++++++++++++++----------- src/lib_base/index.mld | 17 +---------------- 2 files changed, 26 insertions(+), 27 deletions(-) diff --git a/manifest/main.ml b/manifest/main.ml index 38122160764f..b34460be68ce 100644 --- a/manifest/main.ml +++ b/manifest/main.ml @@ -457,7 +457,7 @@ let alcotezt = ~deps:[tezt_core_lib] |> open_ -type sub_lib_documentation_entrypoint = Module | Page +type sub_lib_documentation_entrypoint = Module | Page | Sub_lib type sub_lib = { name : string; @@ -494,11 +494,19 @@ let octez_lib ?internal_name ?js_of_ocaml ?inline_tests ?foreign_stubs | None | Some Dune.[[S "package"; S "octez-libs"]] -> (* In the case that the documentation stanza is only a package declaration, we don't want the page to be used *) - { - name = String.capitalize_ascii name; - synopsis; - documentation_type = Module; - } + if String.contains (Option.value ~default:public_name internal_name) '.' + then + { + name = String.capitalize_ascii name; + synopsis; + documentation_type = Sub_lib; + } + else + { + name = String.capitalize_ascii name; + synopsis; + documentation_type = Module; + } | Some _docs -> {name; synopsis; documentation_type = Page} in registered_octez_libs := registered :: !registered_octez_libs ; @@ -546,25 +554,31 @@ let pp_octez_libs_index fmt registered_octez_libs = in let pp_registered pp = function | {name; synopsis = None; documentation_type = Module} -> - Format.fprintf pp "- {{!module-%s}%s}" name name + Format.fprintf pp "- {{!module-%s}%s}@." name name | {name; synopsis = Some synopsis; documentation_type = Module} -> - Format.fprintf pp "- {{!module-%s}%s}: %s" name name synopsis + Format.fprintf pp "- {{!module-%s}%s}: %s@." name name synopsis | {name; synopsis = None; documentation_type = Page} -> - Format.fprintf pp "- {{!page-%s}%s}" name (String.capitalize_ascii name) + Format.fprintf + pp + "- {{!page-%s}%s}@." + name + (String.capitalize_ascii name) | {name; synopsis = Some synopsis; documentation_type = Page} -> Format.fprintf pp - "- {{!page-%s}%s}: %s" + "- {{!page-%s}%s}: %s@." name (String.capitalize_ascii name) synopsis + | {documentation_type = Sub_lib; _} -> + (* In case it's a sub_lib, we don't link anything *) () in Format.fprintf fmt "%s%a" header (Format.pp_print_list - ~pp_sep:(fun pp () -> Format.fprintf pp "@.") + ~pp_sep:(fun pp () -> Format.fprintf pp "") pp_registered) @@ List.sort (fun {name = name1; _} {name = name2; _} -> diff --git a/src/lib_base/index.mld b/src/lib_base/index.mld index 6b2037463418..d27596c92e0a 100644 --- a/src/lib_base/index.mld +++ b/src/lib_base/index.mld @@ -23,22 +23,11 @@ It contains the following libraries: - {{!module-Plonk_test}Plonk_test} - {{!module-Polynomial}Polynomial}: Polynomials over finite fields - {{!module-Tezos_base}Tezos_base}: Meta-package and pervasive type definitions for Tezos -- {{!module-Tezos_base_p2p_identity_file}Tezos_base_p2p_identity_file} - {{!module-Tezos_base_test_helpers}Tezos_base_test_helpers}: Octez base test helpers -- {{!module-Tezos_base_unix}Tezos_base_unix} - {{!module-Tezos_clic}Tezos_clic} -- {{!module-Tezos_clic_unix}Tezos_clic_unix} - {{!module-Tezos_context}Tezos_context}: On-disk context abstraction for [octez-node] -- {{!module-Tezos_context_disk}Tezos_context_disk} -- {{!module-Tezos_context_dump}Tezos_context_dump} -- {{!module-Tezos_context_encoding}Tezos_context_encoding} -- {{!module-Tezos_context_helpers}Tezos_context_helpers} -- {{!module-Tezos_context_memory}Tezos_context_memory} -- {{!module-Tezos_context_merkle_proof_encoding}Tezos_context_merkle_proof_encoding} -- {{!module-Tezos_context_sigs}Tezos_context_sigs} - {{!module-Tezos_crypto}Tezos_crypto}: Library with all the cryptographic primitives used by Tezos - {{!module-Tezos_crypto_dal}Tezos_crypto_dal}: DAL cryptographic primitives -- {{!module-Tezos_crypto_dal_octez_dal_config}Tezos_crypto_dal_octez_dal_config} - {{!module-Tezos_error_monad}Tezos_error_monad}: Error monad - {{!module-Tezos_event_logging}Tezos_event_logging}: Octez event logging library - {{!module-Tezos_event_logging_test_helpers}Tezos_event_logging_test_helpers}: Test helpers for the event logging library @@ -52,9 +41,6 @@ It contains the following libraries: - {{!module-Tezos_p2p_services}Tezos_p2p_services}: Descriptions of RPCs exported by [tezos-p2p] - {{!module-Tezos_p2p_test_common}Tezos_p2p_test_common} - {{!module-Tezos_protocol_environment}Tezos_protocol_environment} -- {{!module-Tezos_protocol_environment_sigs}Tezos_protocol_environment_sigs} -- {{!module-Tezos_protocol_environment_sigs_internals}Tezos_protocol_environment_sigs_internals} -- {{!module-Tezos_protocol_environment_structs}Tezos_protocol_environment_structs} - {{!module-Tezos_requester}Tezos_requester} - {{!module-Tezos_rpc}Tezos_rpc}: Library of auto-documented RPCs (service and hierarchy descriptions) - {{!module-Tezos_rpc_http}Tezos_rpc_http}: Library of auto-documented RPCs (http server and client) @@ -70,7 +56,6 @@ It contains the following libraries: - {{!module-Tezos_test_helpers}Tezos_test_helpers} - {{!module-Tezos_tree_encoding}Tezos_tree_encoding}: A general-purpose library to encode arbitrary data in Merkle trees - {{!module-Tezos_version}Tezos_version}: Version information generated from Git -- {{!module-Tezos_version_parser}Tezos_version_parser} - {{!module-Tezos_webassembly_interpreter}Tezos_webassembly_interpreter} - {{!page-tezos_workers}Tezos_workers}: Worker library - {{!module-Tezt_performance_regression}Tezt_performance_regression} @@ -78,4 +63,4 @@ It contains the following libraries: - {{!module-Traced_functor_outputs}Traced_functor_outputs} - {{!module-Traced_sigs}Traced_sigs} - {{!module-Traced_structs}Traced_structs} -- {{!module-Traces}Traces} \ No newline at end of file +- {{!module-Traces}Traces} -- GitLab From 70604b0fb16f17ad53f9afe121d8c6e2118ed2c3 Mon Sep 17 00:00:00 2001 From: Killian Delarue Date: Fri, 18 Aug 2023 14:59:40 +0200 Subject: [PATCH 5/5] Manifest: Prevent having two octez-libs with the same internal --- manifest/main.ml | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/manifest/main.ml b/manifest/main.ml index b34460be68ce..b4fbe4772a31 100644 --- a/manifest/main.ml +++ b/manifest/main.ml @@ -509,7 +509,19 @@ let octez_lib ?internal_name ?js_of_ocaml ?inline_tests ?foreign_stubs } | Some _docs -> {name; synopsis; documentation_type = Page} in - registered_octez_libs := registered :: !registered_octez_libs ; + + if + List.exists + (fun registered -> String.equal registered.name name) + !registered_octez_libs + then + invalid_arg + (Format.sprintf + "octez-libs already contains a library that would have the same \ + internal name, %s, as %s" + (Option.value ~default:public_name internal_name) + name) + else registered_octez_libs := registered :: !registered_octez_libs ; public_lib ("octez-libs." ^ public_name) ~internal_name:name -- GitLab