diff --git a/docs/010/glossary.rst b/docs/010/glossary.rst index ba477167dea6510e437886ea6661f05842650ff3..7e141a159e9682d81fe8aa0f04c379c3f2e3f4d8 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 edf929d04675ceb60831b39a5dcdf02afa2e8f4c..f994c7c92a95c855174780f3a7bb1a349f587bb7 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/README.rst b/docs/README.rst index a97644b9c01f0094cd265b4478cfd8fba3e8afa8..57f572f7b7fdf43e5ab1a261af60640b8b842f42 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/alpha/glossary.rst b/docs/alpha/glossary.rst index dac3a85f92c897f17ab7fc95a41e6cf098610f8d..b4fa60a94c9c139203435d53b0b91dbb14d152ff 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/developer/contributing.rst b/docs/developer/contributing.rst index 888a802e133e3ba8495042f06379a661ded04204..21deff3e522e634b3db028ddeb8ed93d6de8860b 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. @@ -580,6 +581,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 diff --git a/docs/developer/event_logging_framework.rst b/docs/developer/event_logging_framework.rst index 571f2f05218d4f1593931cc5cbd8f968a1cd4e50..f4f778d1335e00518cea8449485f7ef9cd3a8902 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/developer/guidelines.rst b/docs/developer/guidelines.rst index b33f8cdd0d7d772886ffc3a56ebe17b9ca7e7bf9..ff1897f9c454e50ff6fc619af0934503cb91cc23 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/developer/howto-freeze-protocols.rst b/docs/developer/howto-freeze-protocols.rst index 07f82c955e11ef4c69f4e4d531a16dc1139e5ecf..3fdb5376fbf4ef9dd01c36494521bb08aa65cb35 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 diff --git a/docs/index.rst b/docs/index.rst index 16a2112d17c7c4bc0d29e3475f04e40336a95722..b297a9b5009a54c46d51aba6c23b8f7f539cc9e5 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 ----- @@ -151,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 @@ -165,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 @@ -180,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 diff --git a/docs/user/logging.rst b/docs/user/logging.rst index f9fe8188e376f8f61965bff57f0ca637dad2ca98..9e42c625c902ca9698a00bd9805f951563e152ee 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`` - diff --git a/docs/user/versioning.rst b/docs/user/versioning.rst index a8c9d18a9123068b01511f646b6011016783a1d0..98bcef4ce9583a3bad5056c6b7d25bd1a2c4a505 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. diff --git a/src/lib_protocol_environment/environment_cache.mli b/src/lib_protocol_environment/environment_cache.mli index 4a5843c301886a816ef1e77dab0fed67b0509b71..28854b698df3d43976871ea292b0fc5dd4567c54 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 cc1891514156cc3bd280e925ddea2943f7b92377..cb6c12cf9613b46bc9d10cb5f5e423e7142617e6 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