From 9c2e546ffc34d67d1d58430dc4f5a94cabd594a4 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 20 Oct 2021 12:11:31 +0200 Subject: [PATCH 1/8] doc: explain doc building in CI --- docs/README.rst | 26 +++++++++++++++++++++++++- docs/developer/contributing.rst | 2 ++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/README.rst b/docs/README.rst index a97644b9c01f..57f572f7b7fd 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -8,7 +8,31 @@ and always up to date with branch ``master`` on `GitLab `_. For instructions on how to obtain Python and Poetry, see :doc:`the installation instructions for the python testing diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 888a802e133e..d8f2374ea470 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -580,6 +580,8 @@ pitfalls a code reviewer should avoid. have a different reaction to it and impact on the quality of this work. This general remark is valid for any comment. +When reviewing MRs involving documentation, you may check the built documentation directly within the Gitlab interface, see :ref:`build_doc_ci`. + .. _merge_bot: The Merge-Request Bot -- GitLab From 11096964f00ca14e9e1377ce5bb0c61b65efc89b Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 20 Oct 2021 14:08:29 +0200 Subject: [PATCH 2/8] doc: when explaining RPC versioning, refer to versioning rules --- docs/developer/guidelines.rst | 4 ++-- docs/user/versioning.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index b33f8cdd0d7d..ff1897f9c454 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -406,8 +406,8 @@ of an RPC. .. _RPC-versioning-dev-adding-an-rpc: -How to Add a New Version to an RPC -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When to Add a New Version to an RPC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you modify the input or the output of an RPC, it is not always necessary to create a new version for the RPC. A new version should be diff --git a/docs/user/versioning.rst b/docs/user/versioning.rst index a8c9d18a9123..98bcef4ce958 100644 --- a/docs/user/versioning.rst +++ b/docs/user/versioning.rst @@ -45,7 +45,7 @@ retrieved easily yet. New Version ~~~~~~~~~~~ -Whenever a new version of an RPC is added, there is a corresponding +Whenever a new version of an RPC is added (see :ref:`RPC-versioning-dev-adding-an-rpc`), there is a corresponding entry in the file :src:`CHANGES.rst` in the release of Octez which includes the new version. -- GitLab From 5636763b9eaf6d2e4a99aefd46b95c5744de627e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 20 Oct 2021 16:28:11 +0200 Subject: [PATCH 3/8] doc: fix Sphinx errors in new pages on event-based logging --- docs/developer/event_logging_framework.rst | 10 +++++----- docs/user/logging.rst | 5 ++--- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/developer/event_logging_framework.rst b/docs/developer/event_logging_framework.rst index 571f2f05218d..f4f778d1335e 100644 --- a/docs/developer/event_logging_framework.rst +++ b/docs/developer/event_logging_framework.rst @@ -2,7 +2,7 @@ Using The Event Logging Framework --------------------------------- Developers of most modules should consider generating useful information -for the :doc:`Logging subsystem <./user/logging>`. +for the :doc:`Logging subsystem <../user/logging>`. In the Octez code base, logging is instrumented using an asynchronous event system, where log events are emitted in various part of the code and consumed by @@ -28,7 +28,7 @@ fields of the events are still evaluated every time, which is usually not an issue since they are evaluated anyway by the application code itself). See for instance -:src:`bin_node/node_config_file.ml` (search for the string "declare_"): +:src:`src/bin_node/node_config_file.ml` (search for the string `declare_`): - one declares typed-record events with ``Internal_event.Simple.declare_``, @@ -45,7 +45,7 @@ The most generic API for defining events ``Internal_event.Make`` gives full expressive power and structure while being 100% lazy. See for instance: -:src:`proto_alpha/lib_delegate/client_baking_blocks.ml` (module +:src:`src/proto_alpha/lib_delegate/client_baking_blocks.ml` (module ``Block_seen_event``): - one needs to call the functor @@ -65,6 +65,6 @@ chosen URI-scheme should be unique. See for instance: - The (simplest) module ``Lwt_log_sink``: - :src:`lib_event_logging/internal_event.ml`, + :src:`src/lib_event_logging/internal_event.ml`, - or, the much more complex, - :src:`lib_stdlib_unix/file_descriptor_sink.ml`. + :src:`src/lib_stdlib_unix/file_descriptor_sink.ml`. diff --git a/docs/user/logging.rst b/docs/user/logging.rst index f9fe8188e376..9e42c625c902 100644 --- a/docs/user/logging.rst +++ b/docs/user/logging.rst @@ -121,7 +121,7 @@ Examples: The format of the events is (usually minified): -.. code:: json +.. code:: javascript {"fd-sink-item.v0": {"hostname": , @@ -181,7 +181,7 @@ JSON Configuration Format A configuration JSON blob, is an object with one field ``"active_sinks"`` which contains a list of URIs: -.. code:: json +.. code:: javascript { "active_sinks": [ ] @@ -297,4 +297,3 @@ This is work-in-progress, see: Example: ``tezos-admin-client output schema of block-seen-alpha to block-seen-alpha.json`` - -- GitLab From 452846c036a2b14802f15a7e4326b68d064b95bd Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 21 Oct 2021 18:54:47 +0200 Subject: [PATCH 4/8] doc: mention design docs in small MRs --- docs/developer/contributing.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index d8f2374ea470..21deff3e522e 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -343,6 +343,7 @@ must be mitigated as follows: - Have the entire piece of work described or done somewhere. For example in an issue, or a branch containing the entire change, or a large (unsplit) work as a draft merge request. + For complex works, an external document may be referred in the issue/MR, detailing the design/implementation rationale; if such documents are only targeted to reviewers and/or are only describing a *change*, they should not go in the online documentation. - Include a link to the entire piece of work in the description of each small merge requests created by splitting the large piece of work. This will help reviewers get the big picture. -- GitLab From 6c5863d6669623c2357c131f783b1203aff7db34 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Mon, 25 Oct 2021 11:35:52 +0200 Subject: [PATCH 5/8] Doc: clarify meaning of ro/rw commands --- docs/developer/howto-freeze-protocols.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/developer/howto-freeze-protocols.rst b/docs/developer/howto-freeze-protocols.rst index 07f82c955e11..3fdb5376fbf4 100644 --- a/docs/developer/howto-freeze-protocols.rst +++ b/docs/developer/howto-freeze-protocols.rst @@ -4,7 +4,7 @@ How to Freeze Protocols After each protocol activation, old protocols are kept in the codebase. However large parts of the code developed for the previous protocol can now be removed to avoid accumulating dead code in the repository. All daemons, tests -associated to old protocols, and RW commands available to the client can be +associated to old protocols, and RW (read-write) commands available to the client can be removed. In this document, "protocol" refers to the protocol that we want to freeze, N, @@ -79,8 +79,11 @@ Integration tests should be amended by running the script Remove RW Commands From ``lib_client_commands`` ----------------------------------------------- -The module `lib_client_commands` defines both read-only and read-write (RW) -commands. The RW commands can now be safely removed as they are no longer +The client commands at +`proto_XXX/lib_client_commands/client_proto_context_commands.ml` +define both read-only and read-write commands, where reads and +writes refer to accesses to and modifications of the state of the +chain. The RW commands can now be safely removed as they are no longer needed. Remove Mempool Protocol Plugins -- GitLab From 95f21d7a5668b6b198daa62a895a42438afe9207 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Mon, 25 Oct 2021 13:26:21 +0200 Subject: [PATCH 6/8] docs: update description of daemons in glossary --- docs/010/glossary.rst | 8 ++++---- docs/011/glossary.rst | 8 ++++---- docs/alpha/glossary.rst | 9 ++++----- docs/index.rst | 2 ++ 4 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/010/glossary.rst b/docs/010/glossary.rst index ba477167dea6..7e141a159e96 100644 --- a/docs/010/glossary.rst +++ b/docs/010/glossary.rst @@ -21,7 +21,7 @@ _`Accuser` The accuser is awarded some funds from the baking_ deposit of the accused. - Using the tools provided by Nomadic Labs, accusation is handled by a + When using :ref:`Octez `, accusations are handled by a separate binary. _`Account` @@ -38,8 +38,8 @@ _`Baker` is allowed to bake; blocks created by another node_ are invalid. The baker selects transactions from the mempool_ to be included in the block_ it bakes. - Using the tools provided by Nomadic Labs, baking_ is handled by a - separate binary. + When using :ref:`Octez `,, baking_ is handled by a separate + binary. _`Baking`/_`Endorsing rights` A delegate_ is allowed to bake/endorse a block_ if he holds the @@ -102,7 +102,7 @@ _`Endorser` operation_. The accounts that emit the block_ are the endorsers of the block_. Endorsement operations_ are included in the next block_. - Using the tools provided by Nomadic Labs, endorsement is handled by a + When using :ref:`Octez `, endorsing is handled by a separate binary. _`Fee` diff --git a/docs/011/glossary.rst b/docs/011/glossary.rst index edf929d04675..f994c7c92a95 100644 --- a/docs/011/glossary.rst +++ b/docs/011/glossary.rst @@ -21,7 +21,7 @@ _`Accuser` The accuser is awarded some funds from the baking_ deposit of the accused. - Using the tools provided by Nomadic Labs, accusation is handled by a + When using :ref:`Octez `, accusations are handled by a separate binary. _`Account` @@ -38,8 +38,8 @@ _`Baker` is allowed to bake; blocks created by another node_ are invalid. The baker selects transactions from the mempool_ to be included in the block_ it bakes. - Using the tools provided by Nomadic Labs, baking_ is handled by a - separate binary. + When using :ref:`Octez `, baking_ is handled by a separate + binary. _`Baking`/_`Endorsing rights` A delegate_ is allowed to bake/endorse a block_ if he holds the @@ -102,7 +102,7 @@ _`Endorser` operation_. The accounts that emit the block_ are the endorsers of the block_. Endorsement operations_ are included in the next block_. - Using the tools provided by Nomadic Labs, endorsement is handled by a + When using :ref:`Octez `, endorsing is handled by a separate binary. _`Fee` diff --git a/docs/alpha/glossary.rst b/docs/alpha/glossary.rst index dac3a85f92c8..b4fa60a94c9c 100644 --- a/docs/alpha/glossary.rst +++ b/docs/alpha/glossary.rst @@ -21,7 +21,7 @@ _`Accuser` The accuser is awarded some funds from the baking_ deposit of the accused. - Using the tools provided by Nomadic Labs, accusation is handled by a + When using :ref:`Octez `, accusations are handled by a separate binary. _`Account` @@ -38,8 +38,8 @@ _`Baker` is allowed to bake; blocks created by another node_ are invalid. The baker selects transactions from the mempool_ to be included in the block_ it bakes. - Using the tools provided by Nomadic Labs, baking_ is handled by a - separate binary. + When using :ref:`Octez `, baking_ is handled by a separate + binary. _`Baking`/_`Endorsing rights` A delegate_ is allowed to bake/endorse a block_ if he holds the @@ -102,8 +102,7 @@ _`Endorser` operation_. The accounts that emit the block_ are the endorsers of the block_. Endorsement operations_ are included in the next block_. - Using the tools provided by Nomadic Labs, endorsement is handled by a - separate binary. + When using :ref:`Octez `, endorsing is handled by a separate binary. _`Fee` To ensure responsible use of computation resources of other nodes, and also to encourage active participation in the consensus protocol, there are some diff --git a/docs/index.rst b/docs/index.rst index 16a2112d17c7..b376125aa2fb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,8 @@ like Bitcoin or Ethereum. It also attempts to come to consensus about how the protocol and the nodes should adapt and upgrade. The website https://tezos.com/ contains more information about the project. +.. _octez: + Octez ----- -- GitLab From f05920c696b5b5426e8ddafeb79285b351202ba7 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 27 Oct 2021 15:49:55 +0200 Subject: [PATCH 7/8] doc: reorder per-protocol pages to keep reference pages at the end --- docs/index.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index b376125aa2fb..b297a9b5009a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -153,10 +153,10 @@ in the :ref:`introduction `. active/consensus active/sapling active/voting + active/liquidity_baking active/glossary active/cli-commands active/rpc - active/liquidity_baking .. toctree:: :maxdepth: 2 @@ -167,11 +167,11 @@ in the :ref:`introduction `. 011/consensus 011/sapling 011/voting + 011/liquidity_baking + 011/timelock 011/glossary 011/cli-commands 011/rpc - 011/liquidity_baking - 011/timelock .. toctree:: :maxdepth: 2 @@ -182,12 +182,12 @@ in the :ref:`introduction `. alpha/consensus alpha/sapling alpha/voting - alpha/glossary - alpha/cli-commands - alpha/rpc alpha/liquidity_baking alpha/timelock alpha/global_constants + alpha/glossary + alpha/cli-commands + alpha/rpc .. toctree:: :maxdepth: 2 -- GitLab From d4fb5a655398bacd1d4f0c7ca68856b87b0c20b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Proust?= Date: Fri, 29 Oct 2021 10:35:48 +0200 Subject: [PATCH 8/8] small doc formatting fixes --- src/lib_protocol_environment/environment_cache.mli | 3 +-- src/lib_stdlib/tzString.mli | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/src/lib_protocol_environment/environment_cache.mli b/src/lib_protocol_environment/environment_cache.mli index 4a5843c30188..28854b698df3 100644 --- a/src/lib_protocol_environment/environment_cache.mli +++ b/src/lib_protocol_environment/environment_cache.mli @@ -25,8 +25,7 @@ (** {2:lru-generic An LRU inter-blocks cache for the economic protocol} *) -(** {b This is for use *within* the {!module:Environment_context} - only. *) +(** {b This is for use *within* the {!module:Environment_context} only.} *) (** diff --git a/src/lib_stdlib/tzString.mli b/src/lib_stdlib/tzString.mli index cc1891514156..cb6c12cf9613 100644 --- a/src/lib_stdlib/tzString.mli +++ b/src/lib_stdlib/tzString.mli @@ -36,8 +36,8 @@ val split_path : string -> string list beginning and end of string. If [limit] is passed, stops after [limit] split(s). [dups] defaults to [true] and [limit] defaults to [max_int]. Examples: - - split ~dup:true ',' ",hello,,world,"] returns ["hello"; "world"] - - split ~dup:false ',' ",,hello,,,world,,"] returns [""; "hello"; ""; ""; "world"; ""] + - [split ~dup:true ',' ",hello,,world,"] returns ["hello"; "world"] + - [split ~dup:false ',' ",,hello,,,world,,"] returns [""; "hello"; ""; ""; "world"; ""] *) val split : char -> ?dup:bool -> ?limit:int -> string -> string list -- GitLab