From 4aab66d559fcb5e1e7821e619b5c1493a84ef921 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 23 Jul 2021 15:00:57 +0200 Subject: [PATCH 1/6] doc: fix labels --- docs/developer/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 61686f0fba92..36af9139e209 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -533,7 +533,7 @@ The code for the bot is at work-in-progress and new warnings and comments will appear little by little. We welcome specific issues or contributions there too. -.. dev_tools: +.. _dev_tools: Developer Tools ~~~~~~~~~~~~~~~ -- GitLab From 475cbf38a4145ebfa0873b280126c4daa0354516 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 26 Jul 2021 15:50:25 +0200 Subject: [PATCH 2/6] doc: fix RST syntax --- docs/developer/protocol_environment.rst | 2 +- docs/developer/unit_testing_legacy_code.rst | 58 ++++++++++----------- 2 files changed, 29 insertions(+), 31 deletions(-) diff --git a/docs/developer/protocol_environment.rst b/docs/developer/protocol_environment.rst index 5597879b5d2f..920c22f4418f 100644 --- a/docs/developer/protocol_environment.rst +++ b/docs/developer/protocol_environment.rst @@ -32,7 +32,7 @@ Here is a quick description of each file in this environment, all located under These files are assembled into a single interface file ``VX.mli`` by a helper program located in ``s_packer/``. - Special cases: the files ``context.mli``, ``fitness.mli``, and - ``updater.mli`` are interfaces that the protocol exposes to the shell. + ``updater.mli`` are interfaces that the protocol exposes to the shell. - Files in the ``structs/vX/`` directory declare compatibility layers for old protocol environments. E.g., ``structs/V0/error_monad_traversors.ml`` contain the code of error-monad-compatible list traversers that used to be part of diff --git a/docs/developer/unit_testing_legacy_code.rst b/docs/developer/unit_testing_legacy_code.rst index d3c7a86c9fc1..38b14b1f3ce7 100644 --- a/docs/developer/unit_testing_legacy_code.rst +++ b/docs/developer/unit_testing_legacy_code.rst @@ -47,7 +47,6 @@ Works best when: - Code and its dependencies are pure, or "pure enough" (e.g. code may contain logging and other unharmful/unimportant side effects) - Dependency tree is not too deep (e.g. if A depends on B which depends on C which depends on D, then it becomes hard to write/read/maintain unit tests) -Function records Using function records ---------------------- @@ -68,11 +67,11 @@ As an example, consider the following ``Counter`` module (signature and implemen type t = { counter : int; } - + let create_from_file () = let counter = int_of_string (Files.read "/tmp/counter.txt") in {counter} - + let increment_and_save_to_file t = let t = {counter = t.counter + 1} in Files.write "/tmp/counter.txt" (string_of_int t.counter); @@ -93,7 +92,7 @@ One way to achieve this - when your module has a state, usually a type ``t`` - i type t val create_from_file : unit -> t val increment_and_save_to_file : t -> t - + module Internal_for_tests : sig type dependencies = { files_read : string -> string; @@ -106,30 +105,30 @@ One way to achieve this - when your module has a state, usually a type ``t`` - i files_read : string -> string; files_write : string -> string -> unit; } - + type t = { counter : int; dependencies : dependencies; } - + let create_from_file_internal dependencies () = let counter = int_of_string (dependencies.files_read "/tmp/counter.txt") in {counter; dependencies} - + let create_from_file = create_from_file_internal {files_read = Files.read; files_write = Files.write} - + let increment_and_save_to_file t = let t = {t with counter = t.counter + 1} in t.dependencies.files_write "/tmp/counter.txt" (string_of_int t.counter); t - + module Internal_for_tests = struct type nonrec dependencies = dependencies = { files_read : string -> string; files_write : string -> string -> unit; } - - let create_from_file = create_from_file_internal + + let create_from_file = create_from_file_internal end end @@ -165,13 +164,13 @@ An alternative solution, more verbose but not requiring any "state" value availa type t val create_from_file : unit -> t val increment_and_save_to_file : t -> t - + module Internal_for_tests : sig type dependencies = { files_read : string -> string; files_write : string -> string -> unit; } - + val create_from_file : dependencies -> unit -> t val increment_and_save_to_file : dependencies -> t -> t end @@ -195,14 +194,14 @@ An alternative solution, more verbose but not requiring any "state" value availa {counter} let create_from_file = create_from_file_internal business_dependencies - + let increment_and_save_to_file_internal dependencies t = let t = {counter = t.counter + 1} in dependencies.files_write "/tmp/counter.txt" (string_of_int t.counter); t - + let increment_and_save_to_file t = increment_and_save_to_file_internal business_dependencies t - + module Internal_for_tests = struct type nonrec dependencies = dependencies = { files_read : string -> string; @@ -264,8 +263,8 @@ To choose between the field and the argument: - Else add a ``dependencies`` argument - but this requires duplicating each function, which ends up being very verbose if you have several functions - If your "state" value (usually a value of type ``t``) is passed to a polymorphic function like ``=`` or ``compare`` (which throw on function fields, and are famous for being an anti-pattern), and it is not possible for you to fix this anti-pattern, then either switch to function arguments, or wrap in an object. -Functors --------- +Using functors +-------------- This approach decouples the business code from its dependency modules. Note that unlike the Function records solution, this decouples both dependency functions **and abstract types**! @@ -291,9 +290,9 @@ Consider the following code: it is similar to the previous ``Counter`` example b type t = { counter : int; } - + let create counter = {counter} - + let increment_and_save_to_file t = let t = {counter = t.counter + 1} in let file = Files.openf "/tmp/counter.txt" in @@ -312,9 +311,9 @@ The technique is to transform ``Counter`` into a functor that takes a module loo val create : int -> t val increment_and_save_to_file : t -> t end - + include S - + module Internal_for_tests : sig module type FILES = sig type t @@ -330,21 +329,21 @@ The technique is to transform ``Counter`` into a functor that takes a module loo val create : int -> t val increment_and_save_to_file : t -> t end - + module type FILES = sig type t val openf : string -> t val write : t -> string -> unit val close : t -> unit end - + module Make (Files : FILES) = struct type t = { counter : int; } - + let create counter = {counter} - + let increment_and_save_to_file t = let t = {counter = t.counter + 1} in let file = Files.openf "/tmp/counter.txt" in @@ -352,13 +351,13 @@ The technique is to transform ``Counter`` into a functor that takes a module loo Files.close file; t end - + (* Do not be mistaken: here [Files] refers to the real, business [Files] module! *) include Make (Files) - + module Internal_for_tests = struct module type FILES = FILES - + module Make = Make end end @@ -403,4 +402,3 @@ Cons: - Additional complexity (functors, module types) - Does not scale well in more complex dependencies (``A`` depends on ``B`` and ``C`` types, and ``B`` also depends on ``C`` types) as it induces a lot of destructive substitutions and module noise to convince the typechecker that ``C.t`` in ``A`` is the same as ``C.t`` in ``B`` - Does not work for exposed and private (exposed in read-only) dependency types - -- GitLab From 108f0ef56fef090f2274545218f83d7dcd34aa70 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 30 Jul 2021 16:34:27 +0200 Subject: [PATCH 3/6] doc: fix some odoc errors --- src/lib_shell/prevalidation.mli | 2 +- src/lib_shell/prevalidator_classification.mli | 2 +- src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml | 2 +- .../lib_protocol/test/helpers/liquidity_baking_machine.mli | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/lib_shell/prevalidation.mli b/src/lib_shell/prevalidation.mli index 6a0abbadd6c3..d431a9092e14 100644 --- a/src/lib_shell/prevalidation.mli +++ b/src/lib_shell/prevalidation.mli @@ -53,7 +53,7 @@ module type T = sig [unsafe] because there are no length checks, unlike {!parse}. - @deprecated You should use {parse} instead. *) + @deprecated You should use [parse] instead. *) val parse_unsafe : bytes -> Proto.operation_data tzresult (** Creates a new prevalidation context w.r.t. the protocol associate to the diff --git a/src/lib_shell/prevalidator_classification.mli b/src/lib_shell/prevalidator_classification.mli index c059830d0384..d7d752cdf9ba 100644 --- a/src/lib_shell/prevalidator_classification.mli +++ b/src/lib_shell/prevalidator_classification.mli @@ -89,7 +89,7 @@ val remove_not_applied : Operation_hash.t -> t -> unit class field is full. In that case, the new operation is added to the class, and the one removed is discarded. An operation is also discarded when it is classified as [Refused]. The callback - [on_discarded_operation] which was given by the function {create} + [on_discarded_operation] which was given by the function [create] when the value [classes] was created is called on each discarded operation. *) val add : diff --git a/src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml b/src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml index 1915a60df644..a1d4d8027c58 100644 --- a/src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml +++ b/src/proto_alpha/lib_protocol/test/helpers/cpmm_logic.ml @@ -27,7 +27,7 @@ open Protocol open Alpha_context (** This is a simulation of the CPMM contract, as implemented in mligo - in {v src/proto_alpha/lib_protocol/contracts/cpmm.mligo v}. The + in [src/proto_alpha/lib_protocol/contracts/cpmm.mligo]. The interested reader should look for comments in this file to gain a better understanding of the contract logic. *) module Simulate_raw = struct diff --git a/src/proto_alpha/lib_protocol/test/helpers/liquidity_baking_machine.mli b/src/proto_alpha/lib_protocol/test/helpers/liquidity_baking_machine.mli index 24d1670afe51..ed8fb9e64ba1 100644 --- a/src/proto_alpha/lib_protocol/test/helpers/liquidity_baking_machine.mli +++ b/src/proto_alpha/lib_protocol/test/helpers/liquidity_baking_machine.mli @@ -55,7 +55,7 @@ open Alpha_context That is, the {! ValidationMachine} reports desynchronization of the two machines, but cannot explain this desynchronization. *) -(** {1 Machine State Characterization} Module Type} *) +(** {1 Machine State Characterization} *) type xtz = int64 -- GitLab From 4df33e2267bae733888aff92b2f2d470475562ba Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 30 Jul 2021 17:53:22 +0200 Subject: [PATCH 4/6] doc: fix some Sphinx warnings --- docs/alpha/timelock.rst | 6 +++--- docs/alpha/voting.rst | 7 ++----- .../contributing-adding-a-new-opam-dependency.rst | 2 -- docs/developer/contributing.rst | 7 ++++++- docs/index.rst | 1 + docs/user/fa12.rst | 2 +- 6 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/alpha/timelock.rst b/docs/alpha/timelock.rst index 38c42b7b0992..3826851e2237 100644 --- a/docs/alpha/timelock.rst +++ b/docs/alpha/timelock.rst @@ -7,7 +7,7 @@ Block Producer Extractable Value We aim at tackling the issue known through the unfortunate misnomer of "generalized front running", described -for instance in `here `_. +for instance in `here `__. Observing a transaction before it is actually included in the chain can give an advantage to a trader against another one. Ultimately, @@ -55,7 +55,7 @@ ensure a level playing field in terms of computational speed. An implementation of the timelock puzzle and proof scheme is available in :src:`src/lib_crypto/timelock.mli` inspired from a proof of concept available -`here `_ +`here `__. General principle ----------------- @@ -81,7 +81,7 @@ Cryptographic principles ------------------------ Users first generate a RSA modulus and a symmetric encryption key. -They use authenticated encryption to encrypt a `PACK`ed Michelson value (i.e., bytes) +They use authenticated encryption to encrypt a packed Michelson value (an array of bytes computed with ``PACK``) and encrypt that encryption key using a timelock puzzle. They then combine the RSA modulus, the timelocked symmetric key, the constant T and the encrypted value as a single value as well (called chest in our library in src/lib_crypto). diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index a04d698013b8..850a782f0ea2 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -1,5 +1,3 @@ -.. _alpha_voting_procedure - The Voting Process ================== @@ -19,8 +17,7 @@ Voting periods align with cycles: a voting period starts at the first block of a cycle. Other than this page, there is an excellent overview from `Jacob -Arluck on medium. -`_ +Arluck on medium `__. Periods ------- @@ -216,4 +213,4 @@ For vote related RPCs check the :doc:`rpc` under the prefix ``votes/``. For Ledger support refer to Obsidian Systems' `documentation -`_. +`__. diff --git a/docs/developer/contributing-adding-a-new-opam-dependency.rst b/docs/developer/contributing-adding-a-new-opam-dependency.rst index bc9281307383..16032e0d1870 100644 --- a/docs/developer/contributing-adding-a-new-opam-dependency.rst +++ b/docs/developer/contributing-adding-a-new-opam-dependency.rst @@ -1,5 +1,3 @@ -.. _adding_new_opam_dependency: - How to add or update opam dependencies ====================================== diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 36af9139e209..ab466d3100f9 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -338,7 +338,12 @@ Special case: MRs that introduce a new dependency In the special case where your MR adds a new opam dependency or updates an existing opam dependency, you will need to follow -:ref:`this additional dedicated guide `. +this additional dedicated guide: + +.. toctree:: + :maxdepth: 2 + + contributing-adding-a-new-opam-dependency In the special case where your MR adds a new Python, Rust, Javascript, or other dependency, additional steps must also be followed. diff --git a/docs/index.rst b/docs/index.rst index d4c99b250901..bce3595e1921 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -180,6 +180,7 @@ in the :ref:`introduction `. alpha/cli-commands alpha/rpc alpha/liquidity_baking + alpha/timelock .. toctree:: :maxdepth: 2 diff --git a/docs/user/fa12.rst b/docs/user/fa12.rst index 754be1f710f2..90f7b4449484 100644 --- a/docs/user/fa12.rst +++ b/docs/user/fa12.rst @@ -86,7 +86,7 @@ optional argument ``--as ``, allowing an approved account `operator` t make transfers from `source` to any other accounts. The JSON format for the transfers is the following: -.. code-block:: json +.. code-block:: javascript [{ "token_contract": , // address or alias of the FA1.2 contract "destination": , // address or alias of the recipient of the transfer -- GitLab From 6e6b508b2d8159736643d2a3810636a0ed168c3d Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 2 Aug 2021 16:13:39 +0200 Subject: [PATCH 5/6] doc: fix bullet lists everywhere --- docs/poetry.lock | 15 ++++++++------- docs/pyproject.toml | 2 +- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/poetry.lock b/docs/poetry.lock index 10d0e2987241..9d066f1b89ed 100644 --- a/docs/poetry.lock +++ b/docs/poetry.lock @@ -57,7 +57,7 @@ test = ["flake8 (==3.7.8)", "hypothesis (==3.55.3)"] [[package]] name = "docutils" -version = "0.17.1" +version = "0.16" description = "Docutils -- Python Documentation Utilities" category = "main" optional = false @@ -208,13 +208,14 @@ test = ["pytest", "pytest-cov", "html5lib", "cython", "typed-ast"] [[package]] name = "sphinx-rtd-theme" -version = "0.5.1" +version = "0.5.2" description = "Read the Docs theme for Sphinx" category = "main" optional = false python-versions = "*" [package.dependencies] +docutils = "<0.17" sphinx = "*" [package.extras] @@ -307,7 +308,7 @@ socks = ["PySocks (>=1.5.6,!=1.5.7,<2.0)"] [metadata] lock-version = "1.1" python-versions = "~3.9" -content-hash = "ba85037512be7d45c3304f810c9e5512731e6b6f22c2e10d19c56f3fe7bd2ab4" +content-hash = "ea1c5f85f2bd02167d7a6b649d7b315381ef32dd3658a33907aa37799e7427ea" [metadata.files] alabaster = [ @@ -335,8 +336,8 @@ commonmark = [ {file = "commonmark-0.9.1.tar.gz", hash = "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60"}, ] docutils = [ - {file = "docutils-0.17.1-py2.py3-none-any.whl", hash = "sha256:cf316c8370a737a022b72b56874f6602acf974a37a9fba42ec2876387549fc61"}, - {file = "docutils-0.17.1.tar.gz", hash = "sha256:686577d2e4c32380bb50cbb22f575ed742d58168cee37e99117a854bcd88f125"}, + {file = "docutils-0.16-py2.py3-none-any.whl", hash = "sha256:0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af"}, + {file = "docutils-0.16.tar.gz", hash = "sha256:c2de3a60e9e7d07be26b7f2b00ca0309c207e06c100f9cc2a94931fc75a478fc"}, ] idna = [ {file = "idna-3.2-py3-none-any.whl", hash = "sha256:14475042e284991034cb48e06f6851428fb14c4dc953acd9be9a5e95c7b6dd7a"}, @@ -419,8 +420,8 @@ sphinx = [ {file = "Sphinx-4.1.0.tar.gz", hash = "sha256:4219f14258ca5612a0c85ed9b7222d54da69724d7e9dd92d1819ad1bf65e1ad2"}, ] sphinx-rtd-theme = [ - {file = "sphinx_rtd_theme-0.5.1-py2.py3-none-any.whl", hash = "sha256:fa6bebd5ab9a73da8e102509a86f3fcc36dec04a0b52ea80e5a033b2aba00113"}, - {file = "sphinx_rtd_theme-0.5.1.tar.gz", hash = "sha256:eda689eda0c7301a80cf122dad28b1861e5605cbf455558f3775e1e8200e83a5"}, + {file = "sphinx_rtd_theme-0.5.2-py2.py3-none-any.whl", hash = "sha256:4a05bdbe8b1446d77a01e20a23ebc6777c74f43237035e76be89699308987d6f"}, + {file = "sphinx_rtd_theme-0.5.2.tar.gz", hash = "sha256:32bd3b5d13dc8186d7a42fc816a23d32e83a4827d7d9882948e7b837c232da5a"}, ] sphinxcontrib-applehelp = [ {file = "sphinxcontrib-applehelp-1.0.2.tar.gz", hash = "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"}, diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 496f43704494..117aaf49058b 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -13,5 +13,5 @@ keywords = ["tezos"] [tool.poetry.dependencies] python = "~3.9" sphinx = "*" -sphinx-rtd-theme = "0.5.1" +sphinx-rtd-theme = "0.5.2" recommonmark = "*" -- GitLab From 37761633e4d2e08b49f5a6a05f4ea20ae5a74381 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 3 Aug 2021 10:47:17 +0200 Subject: [PATCH 6/6] doc: add one phrase explaining the typo train MRs --- docs/developer/contributing.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index ab466d3100f9..5791f4138144 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -30,6 +30,7 @@ Going further You may also want to fix some typos and minor errors or incoherencies in the *documentation*, which is situated in the ``docs/`` subfolder of the code repository. This kind of small contributions can be done without creating a merge request, by directly pushing commits to the ``typo-doc`` branch, which is regularly merged into the master branch, e.g., every one or two weeks. +This periodic merging is implemented by a series of MRs named "the typo train", created for you by a volunteer, and batching the currently pending fixes. Of course, all these commits will be reviewed before being integrated. To directly contribute to the *codebase*, expertise in a few areas is necessary. -- GitLab