diff --git a/docs/009/proof_of_stake.rst b/docs/009/proof_of_stake.rst index 77b1b26b9d9e1286909fe6ce972c6bf623fa4b95..838db927afcc5abbcc2d07af69eb4be2667c81e1 100644 --- a/docs/009/proof_of_stake.rst +++ b/docs/009/proof_of_stake.rst @@ -6,7 +6,7 @@ Proof-of-stake in Tezos This document provides an in-depth description of the Tezos proof-of-stake algorithm as implemented in the current protocol -(namely `PsCARTHA` on `mainnet`). +on `mainnet`. Brief Overview -------------- @@ -342,8 +342,7 @@ the amount of staked tokens is 720,000,000 ꜩ, then roughly 8.74% of this amount is stored in security deposits. This percentage also gives an indication of the minimal amount of tokens a delegate should own in order to not miss out on creating a block or an endorsement. Please -refer to `this section -`_ +refer to :ref:`this section ` of the documentation for a discussion on (over-)delegation. Inflation diff --git a/docs/010/proof_of_stake.rst b/docs/010/proof_of_stake.rst index f3ee170b0e923caf10ef0716adc426bb4b7a8433..3299beed4df56eee5c2ff838315c7cdc3aff511f 100644 --- a/docs/010/proof_of_stake.rst +++ b/docs/010/proof_of_stake.rst @@ -5,7 +5,7 @@ Proof-of-stake in Tezos This document provides an in-depth description of the Tezos proof-of-stake algorithm as implemented in the current protocol -(namely `PsCARTHA` on `mainnet`). +on `mainnet`. Brief Overview -------------- @@ -353,8 +353,7 @@ the amount of staked tokens is 720,000,000 ꜩ, then roughly 8.74% of this amount is stored in security deposits. This percentage also gives an indication of the minimal amount of tokens a delegate should own in order to not miss out on creating a block or an endorsement. Please -refer to `this section -`_ +refer to :ref:`this section ` of the documentation for a discussion on (over-)delegation. Inflation diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index eb2db5c3713e6fe14cd0cd9adb83bfaecd806f6a..2fccfd2321ec25f32c679b7f19fbc97c6b8a493e 100644 --- a/docs/alpha/michelson.rst +++ b/docs/alpha/michelson.rst @@ -486,13 +486,14 @@ Core data types and notations sorted. - ``big_map (k) (t)``: Lazily deserialized maps from keys of type - ``(k)`` of values of type ``(t)``. These maps should be used if one - intends to store large amounts of data in a map. They have higher - gas costs than standard maps as data is lazily deserialized. A - ``big_map`` cannot appear inside another ``big_map``. See the - section on :ref:`operations on big maps ` - for a description of the syntax of values of type ``big_map (k) - (t)`` and available operations. + ``(k)`` of values of type ``(t)``. + These maps should be used if you intend to store large amounts of data in a map. + Using ``big_map`` can reduce gas costs significantly compared to standard maps, as data is lazily deserialized. + Note however that individual operations on ``big_map`` have higher gas costs than those over standard maps. + A ``big_map`` also has a lower storage cost than a standard map of the same size, when large keys are used, since only the hash of each key is stored in a ``big_map``. + + A ``big_map`` cannot appear inside another ``big_map``. + See the section on :ref:`operations on big maps ` for a description of the syntax of values of type ``big_map (k) (t)`` and available operations. Core instructions ----------------- diff --git a/docs/alpha/proof_of_stake.rst b/docs/alpha/proof_of_stake.rst index ad11529851d8db462e332eae0db01d5b20d7347a..63e6692868438566cdf45c0af0b728114638450c 100644 --- a/docs/alpha/proof_of_stake.rst +++ b/docs/alpha/proof_of_stake.rst @@ -5,7 +5,7 @@ Proof-of-stake in Tezos This document provides an in-depth description of the Tezos proof-of-stake algorithm as implemented in the current protocol -(namely `PsCARTHA` on `mainnet`). +on `mainnet`. Brief Overview -------------- @@ -353,8 +353,7 @@ the amount of staked tokens is 720,000,000 ꜩ, then roughly 8.74% of this amount is stored in security deposits. This percentage also gives an indication of the minimal amount of tokens a delegate should own in order to not miss out on creating a block or an endorsement. Please -refer to `this section -`_ +refer to :ref:`this section ` of the documentation for a discussion on (over-)delegation. Inflation diff --git a/docs/developer/contributing-adding-a-new-opam-dependency.rst b/docs/developer/contributing-adding-a-new-opam-dependency.rst index 4b6edb04eb025ac71fcefd1f29df21f817fbca4d..bc92813073839dae47beced32de359e06bce2033 100644 --- a/docs/developer/contributing-adding-a-new-opam-dependency.rst +++ b/docs/developer/contributing-adding-a-new-opam-dependency.rst @@ -28,7 +28,7 @@ between those two components must happen in a specific order. The rest of this document explains the process from the point-of-view of a developer (you). The instructions below assume you have already -`set up your work environment `__ +:ref:`set up your work environment ` but that you installed *development* dependencies (``make build-dev-deps`` instead of ``make build-deps``). diff --git a/docs/developer/python_testing_framework.rst b/docs/developer/python_testing_framework.rst index da72a0ab3b6379b05efec7536d2847a34b4fa185..358546a8ddba6352eb050ee7c7f088297ad17318 100644 --- a/docs/developer/python_testing_framework.rst +++ b/docs/developer/python_testing_framework.rst @@ -35,7 +35,7 @@ Installation Prerequisites: -- A working environment (see `documentation `_) with the binaries compiled, +- A working environment (see :ref:`documentation `) with the binaries compiled, - A local copy of the tezos `repository `_ - `python 3.8.5`. It is recommended to use `pyenv `_ to manage the python versions. If ``pyenv`` diff --git a/docs/developer/snoop_arch.rst b/docs/developer/snoop_arch.rst index a37b5354305ae39acf9ab3ebcce4aa9e6bfa2cef..3382904cbf4ec96a0547b03f221d51f61547670a 100644 --- a/docs/developer/snoop_arch.rst +++ b/docs/developer/snoop_arch.rst @@ -180,7 +180,7 @@ of integers) and output a prediction of execution time (or, up to unit conversion, a quantity of gas). If :math:`S` is the abstract set of sizes, we're trying to infer a function of type :math:`S \rightarrow \mathbb{R}_{\ge 0}` from a finite list of examples :math:`(s_n, t_n)_n \in (S \times \mathbb{R}_{\ge 0})^\ast` -which minimizes some error criterion. This is an example of a _regression_ +which minimizes some error criterion. This is an example of a **regression** problem. Note that since :math:`S` is typically not finite, :math:`S \rightarrow \mathbb{R}_{\ge 0}` @@ -200,9 +200,9 @@ Enumerating the currying isomorphisms, a linear model can be considered as: 1. a **linear** function :math:`\mathbb{R}^n \multimap (S \rightarrow \mathbb{R}_{ge 0})` from "meta" parameters to cost functions; -2. a function :math:`S \rightarrow (\mathbb{R}^n \rightarrow \mathbb{R}_{ge 0})` +2. a function :math:`S \rightarrow (\mathbb{R}^n \rightarrow \mathbb{R}_{\ge 0})` from sizes to linear forms over "meta" parameters; -3. a function :math:`S \times \mathbb{R}^n \rightarrow \mathbb{R}_{ge 0}`. +3. a function :math:`S \times \mathbb{R}^n \rightarrow \mathbb{R}_{\ge 0}`. The two first forms are the useful ones. The first form is useful in stating the inference problem: we seek :math:`\theta` that minimizes some empirical diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index afb0a710f507dc08cbd31dcc12d0c8cc98ec7e6e..e1ed907f7914633bbcc85c2c07505659f9955b36 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -172,6 +172,8 @@ Building from sources via OPAM The easiest way to build the binaries from the source code is to use the OPAM source package manager for OCaml. +.. _build_environment: + Environment ~~~~~~~~~~~ diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst index 58c6eca7819734982e4f06b22cab8e06be22aed1..a5545c567bf273ded8e70d50b87f017e9f9258df 100644 --- a/docs/introduction/howtorun.rst +++ b/docs/introduction/howtorun.rst @@ -81,6 +81,8 @@ using this identity. Otherwise, you need to ask the faucet for more accounts and delegate them to the first. +.. _over_delegation: + Deposits and over-delegation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -236,7 +238,7 @@ If for some reason your delegate is marked inactive you can reactivate it simply by re-registering again like above. To avoid your Tezos delegate being marked inactive while pausing it for maintenance work, it is advised to check the schedule of future baking and endorsing slots assigned to it, using a block explorer in the :ref:`Tezos community `. -Alternatively, you may use the `baking rights RPC `_) and the `endorsing rights RPC `_, able to return a list of baking/endorsing slots for a given delegate. +Alternatively, you may use the :ref:`baking rights RPC `) and the :ref:`endorsing rights RPC `, able to return a list of baking/endorsing slots for a given delegate. .. _baker_run: diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index db0cbbf54214b0434c91e3249b5816b77cb94f65..cb1750d2cc50155932447e8adb91425a5bfaf105 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -219,6 +219,8 @@ Putting together all the above instructions, you may want to run a node as follo # Run the node: tezos-node run --data-dir ~/.tezos-node- --rpc-addr 127.0.0.1 +.. _howtouse_tezos_client: + Client ------ diff --git a/docs/introduction/support.rst b/docs/introduction/support.rst index 6e98cd0f9032cd1d67a3bb1dba269baa5de78712..bf37a6b5da2dd6a9b52f311407165226cf2ad734 100644 --- a/docs/introduction/support.rst +++ b/docs/introduction/support.rst @@ -7,7 +7,7 @@ If you need help understanding how the Tezos protocol works or if you have technical questions about the software, here are a few resources to find answers. -- `This documentation! `_ +- :doc:`This documentation! <../index>` Make sure to go through this technical documentation before asking elsewhere, there is also a search box on the top left corner. - Tezos `Stack Exchange `_ is live diff --git a/docs/protocols/005_babylon.rst b/docs/protocols/005_babylon.rst index 516f534289ead4dc148c35d6ba2f8bc796583c02..889052a2e5633ec7eb8f5d06d172af034099e921 100644 --- a/docs/protocols/005_babylon.rst +++ b/docs/protocols/005_babylon.rst @@ -19,8 +19,8 @@ Gitlab branch. Developers are particularly encouraged to carefully read this page and to monitor it for updates. -More documentation concerning Emmy+ and Michelson is available `here -`_. +More documentation concerning Emmy+ and Michelson is available :doc:`here +<../index>`. .. contents:: Summary of changes diff --git a/docs/user/light.rst b/docs/user/light.rst index 7c5d2cee4882073b011d56cb45baad4d6d8f65af..9c35bce75251bb770c76e734326eb72821446ad0 100644 --- a/docs/user/light.rst +++ b/docs/user/light.rst @@ -4,7 +4,7 @@ Light mode ---------- The ``tezos-client`` described -`here `_ forwards all RPCs to a node. +:ref:`here ` forwards all RPCs to a node. This page describes the *light* mode, a mode where the client performs protocol RPCs locally; like the :ref:`proxy mode`. However, contrary to the proxy mode, the light mode provides diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index 639d9d820cdde24ac51e809823412fa7702e8290..1165101208317ce3019eb1d556dedb18c72c3b6c 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -81,7 +81,7 @@ configuration file would not parse. They are just provided here to help writing your own configuration file if needed. .. literalinclude:: node-config.json - :language: c + :language: javascript The rest of this page provides more details about the use of some selected configuration options/parameters. diff --git a/docs/user/proxy.rst b/docs/user/proxy.rst index 09220f17f52978ea858cae61452bb9deab64d67f..1d26be4fed939fc641302fd6628b72c01e5b40cd 100644 --- a/docs/user/proxy.rst +++ b/docs/user/proxy.rst @@ -4,7 +4,7 @@ Proxy mode ---------- The ``tezos-client`` described -`here `_ forwards all RPCs to a node. +:ref:`here ` forwards all RPCs to a node. This page describes the *proxy* mode, a mode where the client performs protocol RPCs locally. For the computations to be correct, the proxy client requests the data it needs from the node, and uses diff --git a/src/lib_mockup/registration_intf.ml b/src/lib_mockup/registration_intf.ml index d8d3fc023179620bd151bb32b52c91fe0a5bc0de..ffeee5c42d2df0836bea8368497d358a22f75f52 100644 --- a/src/lib_mockup/registration_intf.ml +++ b/src/lib_mockup/registration_intf.ml @@ -48,11 +48,11 @@ module type MOCKUP = sig val protocol_constants_encoding : protocol_constants Data_encoding.t - (** The content equivalent to the default value of {[--protocol-constants]} *) + (** The content equivalent to the default value of [--protocol-constants] *) val default_protocol_constants : Tezos_client_base.Client_context.full -> protocol_constants tzresult Lwt.t - (** The content equivalent to the default value of {[--bootstrap-acounts]} *) + (** The content equivalent to the default value of [--bootstrap-accounts] *) val default_bootstrap_accounts : Tezos_client_base.Client_context.full -> string tzresult Lwt.t diff --git a/src/lib_proxy/proxy_proto.ml b/src/lib_proxy/proxy_proto.ml index 9ec5cda12fee5733bf08d825694ee31644dfd62e..8faea2b998546beb3dddecb1d7fad22c3557eb7e 100644 --- a/src/lib_proxy/proxy_proto.ml +++ b/src/lib_proxy/proxy_proto.ml @@ -46,10 +46,10 @@ module type PROTO_RPC = sig To speed things up, this function returns "v1" on any of these keys, to do a single request instead of two. This list is arbitrary. It was - built by initial input from @klakplok and by experimenting. + built by initial input from \@klakplok and by experimenting. This function guarantees that if it returns Some(prefix, suffix) then - prefix @@ suffix = key. + prefix \@\@ suffix = key. *) val split_key : Proxy_context.M.key -> (Proxy_context.M.key * Proxy_context.M.key) option diff --git a/src/lib_sapling/core_sig.ml b/src/lib_sapling/core_sig.ml index 3ea21d7156e17f8014a3d77b2205f594de30525d..1cafd0a66585e54676c2e75892fe4b4cc035fe5a 100644 --- a/src/lib_sapling/core_sig.ml +++ b/src/lib_sapling/core_sig.ml @@ -289,7 +289,7 @@ module type Validator = sig This function must be called before any of the proving and verification functions requiring a context. Usually you should not need to call this function directly as it is done - by the fist call to `with_{proving,verification}_ctx`. + by the fist call to `with_\{proving,verification\}_ctx`. However you can call this function in order to: - pay its cost upfront and have more predictable latency later - make sure that the parameters are present in the system and avoid a diff --git a/src/lib_shell/p2p_reader.mli b/src/lib_shell/p2p_reader.mli index 459802298f256d44452297be333caa6b5758011b..708c0fe6e5e738a29e3931e9054c30c84cfdaf68 100644 --- a/src/lib_shell/p2p_reader.mli +++ b/src/lib_shell/p2p_reader.mli @@ -89,8 +89,8 @@ - [Get_current_head chain_id]: message is ignored if the chain [chain_id] is inactive for the remote peer. Otherwise, replies with [Current_head (chain_id, head, mempool)] where - [head] is the current head for the requested chain. [mempool is the current - [mempool], or an empty mempool if the remote peer's mempool is disabled. + [head] is the current head for the requested chain. [mempool] is the current + mempool, or an empty mempool if the remote peer's mempool is disabled. - [Current_head (chain_id, header, mempool)]: message is ignored if the chain [chain_id] is inactive for the remote peer. diff --git a/src/lib_shell_services/history_mode.mli b/src/lib_shell_services/history_mode.mli index 1b3f6c9a61bb67faa49bfcb84834dd07b4a1dc12..bfaedef8bbed3b28d80151aa753f54b862d5c084 100644 --- a/src/lib_shell_services/history_mode.mli +++ b/src/lib_shell_services/history_mode.mli @@ -77,7 +77,7 @@ val pp_short : Format.formatter -> t -> unit val tag : t Tag.def (** The module for handling legacy history modes. It is only used for - legacy support, see {lib_store/Legacy} and {lib_store/Snapshots}. + legacy support, see {!Tezos_store.Legacy} and {!Tezos_store.Snapshots}. *) module Legacy : sig type t = Archive | Full | Rolling diff --git a/src/lib_stdlib_unix/lwt_utils_unix.mli b/src/lib_stdlib_unix/lwt_utils_unix.mli index 1ce14d6fb2bcd2d9f12b6470c761bc779391e62d..bce57a7ab98ff2aa82297508ef9ecf68547cd764 100644 --- a/src/lib_stdlib_unix/lwt_utils_unix.mli +++ b/src/lib_stdlib_unix/lwt_utils_unix.mli @@ -86,7 +86,7 @@ val create_dir : ?perm:int -> string -> unit Lwt.t (** [copy_dir ?perm src dst] copies the content of directory [src] in a fresh directory [dst] created with [perm] (0o755 by default). - @raise [Unix_error (ENOTDIR, _, _)] if the given file is not a + @raise Unix_error(ENOTDIR,_,_) if the given file is not a directory. *) val copy_dir : ?perm:int -> string -> string -> unit Lwt.t diff --git a/src/lib_test_services/test_services.ml b/src/lib_test_services/test_services.ml index 02f6f8b2826c06f70d6d1b59051e8c362384f85a..b56b0acb17fe373b1f69a0daa4fa4489adfe1606 100644 --- a/src/lib_test_services/test_services.ml +++ b/src/lib_test_services/test_services.ml @@ -106,7 +106,7 @@ module Mock_sink : sig an event [e], and fails with the assertion message [str] if not. If [filter] is set, only the events whose section is [filter] are searched. If [strict] is set, then [e] must be the only event recorded - (subject to [filter). *) + (subject to [filter]). *) val assert_has_event : string -> ?filter:filter -> ?strict:bool -> pattern -> unit @@ -114,7 +114,7 @@ module Mock_sink : sig recorded the list of events [es], and fails with the assertion message [str] if not. If [filter] is set, only the events whose section is [filter] are searched. If [strict] is set, then [es] must be the only - events recorded (subject to [filter). *) + events recorded (subject to [filter]). *) val assert_has_events : string -> ?filter:filter -> ?strict:bool -> pattern list -> unit diff --git a/src/proto_010_PtGRANAD/lib_benchmark/lib_benchmark_type_inference/mikhailsky.mli b/src/proto_010_PtGRANAD/lib_benchmark/lib_benchmark_type_inference/mikhailsky.mli index c9ceba9c04cfb14e8d2ff86e3265e1c0df540261..6285f6a39555d38ac12cdf88b2b9ff3331ca090e 100644 --- a/src/proto_010_PtGRANAD/lib_benchmark/lib_benchmark_type_inference/mikhailsky.mli +++ b/src/proto_010_PtGRANAD/lib_benchmark/lib_benchmark_type_inference/mikhailsky.mli @@ -31,7 +31,7 @@ open Protocol (** Michelson code is a hard to type-check and generate incrementally due to the presence of ambiguous constructs, such as literals - like '{ 1 ; 2 ; 3 }'. Is it a list of ints? of nats? of tez? Or a set? + like [{ 1 ; 2 ; 3 }]. Is it a list of ints? of nats? of tez? Or a set? Thus, we will work with Mikhailsky, a better behaved version of Michelson allowing local reconstruction of types. diff --git a/src/proto_alpha/lib_benchmark/lib_benchmark_type_inference/mikhailsky.mli b/src/proto_alpha/lib_benchmark/lib_benchmark_type_inference/mikhailsky.mli index 6f465e6c8e0d6657f9f9528c4838a4d7cc0f0562..443b7f8a9dc49bbfb8d719f6009aa4c02486a9c0 100644 --- a/src/proto_alpha/lib_benchmark/lib_benchmark_type_inference/mikhailsky.mli +++ b/src/proto_alpha/lib_benchmark/lib_benchmark_type_inference/mikhailsky.mli @@ -31,7 +31,7 @@ open Tezos_protocol_alpha.Protocol (** Michelson code is a hard to type-check and generate incrementally due to the presence of ambiguous constructs, such as literals - like '{ 1 ; 2 ; 3 }'. Is it a list of ints? of nats? of tez? Or a set? + like [{ 1 ; 2 ; 3 }]. Is it a list of ints? of nats? of tez? Or a set? Thus, we will work with Mikhailsky, a better behaved version of Michelson allowing local reconstruction of types. diff --git a/tezt/lib_tezos/RPC.mli b/tezt/lib_tezos/RPC.mli index 4213a0deb9bd0d29e161e93641f7da222e37a48b..7a66205402bf08cfc883b05e0d416e985e22622f 100644 --- a/tezt/lib_tezos/RPC.mli +++ b/tezt/lib_tezos/RPC.mli @@ -25,7 +25,7 @@ (** In all RPCs, default [chain] is "main" and default [block] is "head". *) -(** {2 Shell RPCs *) +(** {2 Shell RPCs} *) (** Call RPC /network/connections if [peer_id] is [None]. Call RPC /network/connections/[peer_id] otherwise. *) @@ -136,7 +136,7 @@ val post_forge_operations : Client.t -> JSON.t Lwt.t -(** {2 Protocol RPCs *) +(** {2 Protocol RPCs} *) (** Call RPC /chain/[chain]/blocks/[block]/context/constants *) val get_constants :