From f27e8ae572ff531729172a563751b3f9b9916de6 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 25 Mar 2021 15:32:02 +0000 Subject: [PATCH 1/5] fix typos and links --- docs/developer/testing.rst | 4 ++-- docs/introduction/howtoget.rst | 12 ++++++------ docs/introduction/howtouse.rst | 5 +++-- docs/protocols/alpha.rst | 3 +-- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/developer/testing.rst b/docs/developer/testing.rst index 5ed41d9bd530..624cef18e9b0 100644 --- a/docs/developer/testing.rst +++ b/docs/developer/testing.rst @@ -144,7 +144,7 @@ Typical use cases: randomized inputs. Example test: - - QCheck is used in :src:`src/lib_base/test/test_time.ml` to test the :src:`Tezos_base.Time` module. For instance, subtracting and then adding a random amount of seconds to a random time should give back the original time: this tests that ``add`` and ``diff`` are consistent (and the inverse of each other). To run this test, you need to run ``dune exec src/lib_base/test/test_time.exe``. + - QCheck is used in :src:`src/lib_base/test/test_time.ml` to test the `Tezos_base.Time `_ module. For instance, subtracting and then adding a random amount of seconds to a random time should give back the original time: this tests that ``add`` and ``diff`` are consistent (and the inverse of each other). To run this test, you need to run ``dune exec src/lib_base/test/test_time.exe``. References: - `QCheck README `_ @@ -539,7 +539,7 @@ Conventions Besides implementing tests, it is necessary to comment test files as much as possible to keep a maintainable project for future -contributors. As part of this effort, we require that contributors +contributors. As part of this effort, we require that contributors follow this convention: 1. For each unit test module, add a header that explains the overall diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index 55fc2e16384d..5bad29a036af 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -35,7 +35,7 @@ convenience of the installation step (and of upgrading steps), but also efficiency and security considerations. For instance, static binaries have a different memory footprint compared to dynamically-linked binaries. Also, compiling the sources in the official Tezos -repository is more secure than installing OPAM packages from a repository which +repository is more secure than installing OPAM packages from a repository that is not under Tezos control. In particular, compiling from sources enforces a fixed set of dependencies; when compiling via OPAM, this set of dependencies may change, which may or may not be compatible with your security practices. .. _getting_static_binaries: @@ -82,7 +82,7 @@ Fedora Copr repository with Tezos packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you're using Fedora, you can install packages with Tezos binaries from the Copr repository. -Currently it supports Fedora 32 and 31. In order to dd the Copr repository to your machine and install the binaries, run the following commands: +Currently it supports Fedora 32 and 33. In order to dd the Copr repository to your machine and install the binaries, run the following commands: .. literalinclude:: install-bin-fedora.sh :language: shell @@ -203,7 +203,7 @@ release) directly as OPAM packages. .. note:: Every file related to OPAM is (by default) in ``$HOME/.opam`` which - means that, first, OPAM installs are user specific and, second, you + means that, first, OPAM installs are user-specific and, second, you can get rid of everything by removing this directory (+ updating your rc files (``$HOME/.bashrc``, ``$HOME/.profile``, ``$HOME/.zshrc``, ``$HOME/.emacs``, ...) if you asked/allowed OPAM @@ -341,7 +341,7 @@ if file ``.cargo`` does not exist in your home directory. Install Zcash Parameters ~~~~~~~~~~~~~~~~~~~~~~~~ -Tezos binaries requires the Zcash parameter files to run. +Tezos binaries require the Zcash parameter files to run. Docker images come with those files, and the source distribution also includes those files. But if you compile from source and move Tezos to another location (such as ``/usr/local/bin``), the Tezos binaries may @@ -391,7 +391,7 @@ Install the OCaml compiler and the libraries that Tezos depends on:: make build-deps -Alternatively, if you want to to install extra +Alternatively, if you want to install extra development packages such as ``merlin``, you may use the following command instead: @@ -430,7 +430,7 @@ refer to the new switch and compile the project: :start-after: [compile sources] :end-before: [optional setup] -Lastly you can also add the Tezos binaries to your ``PATH`` variable, +Lastly, you can also add the Tezos binaries to your ``PATH`` variable, and after reading the Disclaimer a few hundred times you are allowed to disable it with ``TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y``. diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index e12f630571e2..24b4f6ef2120 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -419,11 +419,12 @@ In Tezos there are two kinds of accounts: *implicit accounts* and *smart contrac Let's originate our first contract and call it *id*:: tezos-client originate contract id transferring 1 from alice \ - running ./tests_python/contracts/attic/id.tz \ + running ./tests_python/contracts_alpha/attic/id.tz \ --init '"hello"' --burn-cap 0.4 The initial balance is ęś©1, generously provided by implicit account -*alice*. The contract stores a Michelson program ``id.tz``, with +*alice*. The contract stores a Michelson program ``id.tz`` +(found in file :src:`./tests_python/contracts_alpha/attic/id.tz`), with Michelson value ``"hello"`` as initial storage (the extra quotes are needed to avoid shell expansion). The parameter ``--burn-cap`` specifies the maximal fee the user is willing to pay for this diff --git a/docs/protocols/alpha.rst b/docs/protocols/alpha.rst index 654961597381..00a70fbb977c 100644 --- a/docs/protocols/alpha.rst +++ b/docs/protocols/alpha.rst @@ -15,5 +15,4 @@ to Florence. .. contents:: Summary of changes -- Fix handling of potential integer overflow in `Time_repr` addition - `Protocol/time_repr: check for potential overflow on addition `_ +- Fix handling of potential integer overflow in `Time_repr` addition `Protocol/time_repr: check for potential overflow on addition `_ -- GitLab From 809e4eae4c6da9eca66ab60ed50fb8af5dc8dd8e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 26 Mar 2021 10:41:54 +0100 Subject: [PATCH 2/5] doc: allow line number suffix in :src: role --- docs/README.rst | 3 ++- docs/_extensions/tezos_custom_roles.py | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index 6180538e5c51..dbc46bbfe45e 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -85,7 +85,8 @@ Some ad-hoc reference kinds are supported. exists - ``:src:`/path/to/file/or/dir``` or ``:src:`text``` points to the gitlab source - tree viewer + tree viewer. It is possible to refer to a particular line in a file by adding + a line number suffix of the form ``#Lnnn``. - ``:opam:`package``` or ``:opam:`text``` points to the package page on ``opam.ocaml.org``, version number is supported (``package.version``) diff --git a/docs/_extensions/tezos_custom_roles.py b/docs/_extensions/tezos_custom_roles.py index 7449d18d90cb..006a59d34cb5 100644 --- a/docs/_extensions/tezos_custom_roles.py +++ b/docs/_extensions/tezos_custom_roles.py @@ -78,9 +78,10 @@ def src_role(name, rawtext, text, lineno, inliner, options={}, content=[]): text = text # raise a warning if the file does not exist - if not Path(TEZOS_HOME, src).exists(): + file = re.sub("#L[0-9]+$", "", src) # drop line number if present + if not Path(TEZOS_HOME, file).exists(): msg = [inliner.reporter.warning( - f'source file {src} does not exist in the repo', + f'source file {file} does not exist in the repo', line=lineno )] else: -- GitLab From 12a8a315da1eb7dde49a38415b0af7510dce9252 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 30 Mar 2021 22:57:18 +0200 Subject: [PATCH 3/5] doc: bugfix in :src: role --- docs/_extensions/tezos_custom_roles.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_extensions/tezos_custom_roles.py b/docs/_extensions/tezos_custom_roles.py index 006a59d34cb5..1fffb91838d8 100644 --- a/docs/_extensions/tezos_custom_roles.py +++ b/docs/_extensions/tezos_custom_roles.py @@ -71,8 +71,8 @@ def src_role(name, rawtext, text, lineno, inliner, options={}, content=[]): rel_lvl = inliner.document.current_source.replace(os.getcwd(),'').count('/') parts = re.match("^([^<>]*)<([^<>]*)>$", text) if parts: - text = parts.group(2) - src = parts.group(1) + text = parts.group(1) + src = parts.group(2) else: src = text text = text -- GitLab From 7ee1969552c0b0dd201e46838827f79e9c689b11 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Mon, 29 Mar 2021 19:38:37 +0200 Subject: [PATCH 4/5] Doc/Michelson: RST fixes in */michelson.rst --- docs/008/michelson.rst | 20 ++++++++++---------- docs/009/michelson.rst | 23 ++++++++++++----------- docs/alpha/michelson.rst | 20 ++++++++++---------- 3 files changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/008/michelson.rst b/docs/008/michelson.rst index 8e1d787b2934..2b2fb4ecd422 100644 --- a/docs/008/michelson.rst +++ b/docs/008/michelson.rst @@ -485,7 +485,7 @@ Core data types and notations of type ``(t)`` that we write ``{ Elt key value ; ... }``, with keys sorted. -- ``big_map (k) (t)``: Lazily deserialized maps from keys of type +- ``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 @@ -578,7 +578,7 @@ result (second rule below). Its type is thus completely generic. > DIP code / x : S => x : S' where code / S => S' -- ``DIP n code``: Runs code protecting the ``n`` topmost elements of +- ``DIP n code``: Runs code protecting the ``n`` topmost elements of the stack. In particular, ``DIP 0 code`` is equivalent to ``code`` and ``DIP 1 code`` is equivalent to ``DIP code``. @@ -1874,15 +1874,15 @@ contract, unit for an account. :: option key_hash : 'S -> operation : 'S Using this instruction is the only way to modify the delegation of a -smart contract. If the parameter is `None` then the delegation of the -current contract is withdrawn; if it is `Some kh` where `kh` is the +smart contract. If the parameter is ``None`` then the delegation of the +current contract is withdrawn; if it is ``Some kh`` where ``kh`` is the key hash of a registered delegate that is not the current delegate of the contract, then this operation sets the delegate of the contract to -this registered delegate. The operation fails if `kh` is the current -delegate of the contract or if `kh` is not a registered delegate. +this registered delegate. The operation fails if ``kh`` is the current +delegate of the contract or if ``kh`` is not a registered delegate. - ``BALANCE``: Push the current amount of mutez held by the executing - contract, including any mutez added by the calling transaction. + contract, including any mutez added by the calling transaction. :: @@ -1968,7 +1968,7 @@ of the contract in which the ``SELF_ADDRESS`` instruction is written. :: key_hash : 'S -> contract unit : 'S -- ``VOTING_POWER``: Return the voting power of a given contract. This voting power +- ``VOTING_POWER``: Return the voting power of a given contract. This voting power coincides with the weight of the contract in the voting listings (i.e., the rolls count) which is calculated at the beginning of every voting period. @@ -2173,7 +2173,7 @@ BLS12-381 primitives :: bls12_381_g2 : bls12_381_g2 : 'S -> bls12_381_g2 : 'S :: bls12_381_fr : bls12_381_fr : 'S -> bls12_381_fr : 'S -- ``MUL``: Multiply a curve point or field element by a scalar field element. Fr +- ``MUL``: Multiply a curve point or field element by a scalar field element. Fr elements can be built from naturals by multiplying by the unit of Fr using ``PUSH bls12_381_fr 1; MUL``. Note that the multiplication will be computed using the natural modulo the order of Fr. @@ -2987,7 +2987,7 @@ stack accept ``n`` variable annotations. > CA(\rest=[AD]+)R @annot %field_name / S => CAR ; C(\rest)R @annot %field_name / S > CD(\rest=[AD]+)R @annot %field_name / S => CDR ; C(\rest)R @annot %field_name / S - ``CMP{EQ|NEQ|LT|GT|LE|GE}`` @annot + CMP{EQ|NEQ|LT|GT|LE|GE} @annot > CMP(\op) @annot / S => COMPARE ; (\op) @annot / S The variable annotation on ``SET_C[AD]+R`` and ``MAP_C[AD]+R`` annotates diff --git a/docs/009/michelson.rst b/docs/009/michelson.rst index b5ebec556877..90b5def24ff1 100644 --- a/docs/009/michelson.rst +++ b/docs/009/michelson.rst @@ -485,7 +485,7 @@ Core data types and notations of type ``(t)`` that we write ``{ Elt key value ; ... }``, with keys sorted. -- ``big_map (k) (t)``: Lazily deserialized maps from keys of type +- ``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 @@ -578,7 +578,7 @@ result (second rule below). Its type is thus completely generic. > DIP code / x : S => x : S' where code / S => S' -- ``DIP n code``: Runs code protecting the ``n`` topmost elements of +- ``DIP n code``: Runs code protecting the ``n`` topmost elements of the stack. In particular, ``DIP 0 code`` is equivalent to ``code`` and ``DIP 1 code`` is equivalent to ``DIP code``. @@ -825,6 +825,7 @@ branches. - ``NEVER``: Close a forbidden branch. :: + :: never : 'A -> 'B - ``COMPARE``: Trivial comparison on type ``never`` @@ -1871,15 +1872,15 @@ contract, unit for an account. :: option key_hash : 'S -> operation : 'S Using this instruction is the only way to modify the delegation of a -smart contract. If the parameter is `None` then the delegation of the -current contract is withdrawn; if it is `Some kh` where `kh` is the +smart contract. If the parameter is ``None`` then the delegation of the +current contract is withdrawn; if it is ``Some kh`` where ``kh`` is the key hash of a registered delegate that is not the current delegate of the contract, then this operation sets the delegate of the contract to -this registered delegate. The operation fails if `kh` is the current -delegate of the contract or if `kh` is not a registered delegate. +this registered delegate. The operation fails if ``kh`` is the current +delegate of the contract or if ``kh`` is not a registered delegate. - ``BALANCE``: Push the current amount of mutez held by the executing - contract, including any mutez added by the calling transaction. + contract, including any mutez added by the calling transaction. :: @@ -1966,8 +1967,8 @@ of the contract in which the ``SELF_ADDRESS`` instruction is written. :: key_hash : 'S -> contract unit : 'S - ``VOTING_POWER``: Return the voting power of a given contract. This voting power - coincides with the weight of the contract in the voting listings (i.e., the rolls - count) which is calculated at the beginning of every voting period. + coincides with the weight of the contract in the voting listings (i.e., the rolls + count) which is calculated at the beginning of every voting period. :: @@ -2170,7 +2171,7 @@ BLS12-381 primitives :: bls12_381_g2 : bls12_381_g2 : 'S -> bls12_381_g2 : 'S :: bls12_381_fr : bls12_381_fr : 'S -> bls12_381_fr : 'S -- ``MUL``: Multiply a curve point or field element by a scalar field element. Fr +- ``MUL``: Multiply a curve point or field element by a scalar field element. Fr elements can be built from naturals by multiplying by the unit of Fr using ``PUSH bls12_381_fr 1; MUL``. Note that the multiplication will be computed using the natural modulo the order of Fr. @@ -2982,7 +2983,7 @@ stack accept ``n`` variable annotations. > CA(\rest=[AD]+)R @annot %field_name / S => CAR ; C(\rest)R @annot %field_name / S > CD(\rest=[AD]+)R @annot %field_name / S => CDR ; C(\rest)R @annot %field_name / S - ``CMP{EQ|NEQ|LT|GT|LE|GE}`` @annot + CMP{EQ|NEQ|LT|GT|LE|GE} @annot > CMP(\op) @annot / S => COMPARE ; (\op) @annot / S The variable annotation on ``SET_C[AD]+R`` and ``MAP_C[AD]+R`` annotates diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index 75864005cf8a..eb2db5c3713e 100644 --- a/docs/alpha/michelson.rst +++ b/docs/alpha/michelson.rst @@ -485,7 +485,7 @@ Core data types and notations of type ``(t)`` that we write ``{ Elt key value ; ... }``, with keys sorted. -- ``big_map (k) (t)``: Lazily deserialized maps from keys of type +- ``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 @@ -578,7 +578,7 @@ result (second rule below). Its type is thus completely generic. > DIP code / x : S => x : S' where code / S => S' -- ``DIP n code``: Runs code protecting the ``n`` topmost elements of +- ``DIP n code``: Runs code protecting the ``n`` topmost elements of the stack. In particular, ``DIP 0 code`` is equivalent to ``code`` and ``DIP 1 code`` is equivalent to ``DIP code``. @@ -1872,15 +1872,15 @@ contract, unit for an account. :: option key_hash : 'S -> operation : 'S Using this instruction is the only way to modify the delegation of a -smart contract. If the parameter is `None` then the delegation of the -current contract is withdrawn; if it is `Some kh` where `kh` is the +smart contract. If the parameter is ``None`` then the delegation of the +current contract is withdrawn; if it is ``Some kh`` where ``kh`` is the key hash of a registered delegate that is not the current delegate of the contract, then this operation sets the delegate of the contract to -this registered delegate. The operation fails if `kh` is the current -delegate of the contract or if `kh` is not a registered delegate. +this registered delegate. The operation fails if ``kh`` is the current +delegate of the contract or if ``kh`` is not a registered delegate. - ``BALANCE``: Push the current amount of mutez held by the executing - contract, including any mutez added by the calling transaction. + contract, including any mutez added by the calling transaction. :: @@ -1966,7 +1966,7 @@ of the contract in which the ``SELF_ADDRESS`` instruction is written. :: key_hash : 'S -> contract unit : 'S -- ``VOTING_POWER``: Return the voting power of a given contract. This voting power +- ``VOTING_POWER``: Return the voting power of a given contract. This voting power coincides with the weight of the contract in the voting listings (i.e., the rolls count) which is calculated at the beginning of every voting period. @@ -2171,7 +2171,7 @@ BLS12-381 primitives :: bls12_381_g2 : bls12_381_g2 : 'S -> bls12_381_g2 : 'S :: bls12_381_fr : bls12_381_fr : 'S -> bls12_381_fr : 'S -- ``MUL``: Multiply a curve point or field element by a scalar field element. Fr +- ``MUL``: Multiply a curve point or field element by a scalar field element. Fr elements can be built from naturals by multiplying by the unit of Fr using ``PUSH bls12_381_fr 1; MUL``. Note that the multiplication will be computed using the natural modulo the order of Fr. @@ -2983,7 +2983,7 @@ stack accept ``n`` variable annotations. > CA(\rest=[AD]+)R @annot %field_name / S => CAR ; C(\rest)R @annot %field_name / S > CD(\rest=[AD]+)R @annot %field_name / S => CDR ; C(\rest)R @annot %field_name / S - ``CMP{EQ|NEQ|LT|GT|LE|GE}`` @annot + CMP{EQ|NEQ|LT|GT|LE|GE} @annot > CMP(\op) @annot / S => COMPARE ; (\op) @annot / S The variable annotation on ``SET_C[AD]+R`` and ``MAP_C[AD]+R`` annotates -- GitLab From efc758b05c69f3d94c51ead5df0a27904235105f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 31 Mar 2021 19:03:50 +0200 Subject: [PATCH 5/5] doc: update copyright years --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index a1bc01d5e70a..dde1bad631d5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,7 +50,7 @@ master_doc = 'index' # General information about the project. project = 'Tezos' -copyright = '2018, Nomadic Labs ' +copyright = '2018-2021, Nomadic Labs ' author = 'Nomadic Labs ' # The version info for the project you're documenting, acts as replacement for -- GitLab