From 809d5bd69040da3b61928a3a9a49435b576093cd Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 4 Jun 2021 17:10:03 +0200 Subject: [PATCH 1/5] doc: rename typo train branch --- docs/developer/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 118a7d13df70..132840e851a7 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -28,8 +28,8 @@ while Z was expected*). 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 contribution can be done without creating a merge request, by directly pushing commits to the ``typo-train`` branch, which is regularly merged into the master branch, e.g., every one or two weeks. +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. 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 From ce04a3e7c981770d326e33c6989ab74cd481713d Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 4 Jun 2021 17:53:01 +0200 Subject: [PATCH 2/5] doc: recommend using "active/" for the current protocol --- docs/README.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/README.rst b/docs/README.rst index fde410deca89..ebd07a4c12cd 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -102,8 +102,9 @@ Links +When introducing cross-references between documentation pages as well as references to external resources, please consider using the most appropriate kind of link: -- When referring to a whole documentation page, you may use a ``:doc:`` role instead of introducing a label at the start of the page. +- When referring to a whole documentation page, you should use a ``:doc:`` role rather than introducing a label at the start of the page. Indeed, labels incur an overhead, especially when pages get duplicated for different protocol versions. + In particular, when referring to a page of the currently active protocol, consider using ``active/`` as the directory of that page, instead of a hardcoded protocol number ``NNN/``. - When referring to an artifact in the code repository (source file, commit, etc.), you may use an appropriate custom or GitLab role (see `Sphinx extensions`_) instead of a plain HTML link. Indeed, specific roles are checked for correctness more effectively and more efficiently than HTML links. @@ -230,6 +231,8 @@ Documenting protocols Due to the duplication of the documentation for multiple protocol versions, the following extra guidelines should be observed. - In principle, protocol-independent pages should only refer to the currently active protocol. Indeed, until newer protocols are adopted, there is no guarantee that their features will be part of Tezos someday. + Note that there is a symbolic link called ``active`` within the documentation folder pointing to the currently active protocol directory. + Use it whenever appropriate to avoid introducing hardcoded protocol numbers. - When modifying the pages of a given protocol version, you might have to also modify it for later versions. Otherwise, when newer protocols are adopted, your changes will vanish! In particular, when fixing a problem in the documentation of the current protocol (e.g. adding a term in the glossary), you might have to fix it also for the candidate protocol (if there is one under the voting procedure) and for the Alpha protocol under development (assuming that the features of the candidate protocol will be inherited by or proposed in another form in Alpha). -- GitLab From b2b4a091d970e0ff30c72950e669137dd082b1ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Cauderlier?= Date: Thu, 10 Jun 2021 17:54:52 +0200 Subject: [PATCH 3/5] doc: typos --- docs/README.rst | 6 +++--- src/proto_alpha/lib_protocol/tez_repr.ml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index ebd07a4c12cd..7d6efd274562 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -100,7 +100,7 @@ For that, you should build the documentation (by running ``make`` in the ``docs` Links ~~~~~ -+When introducing cross-references between documentation pages as well as references to external resources, please consider using the most appropriate kind of link: +When introducing cross-references between documentation pages as well as references to external resources, please consider using the most appropriate kind of link: - When referring to a whole documentation page, you should use a ``:doc:`` role rather than introducing a label at the start of the page. Indeed, labels incur an overhead, especially when pages get duplicated for different protocol versions. @@ -135,8 +135,8 @@ Executable documentation allows one to test those scripts, e.g. in CI (continuou Typically, Tezos installation scripts not only have to evolve with the Tezos codebase, but also with various other evolving resources, such as OPAM packages, package managers, Linux distrbutions, and so on. By continuously testing such installation scripts, executable documentation allows one to detect problems and fix obsolete instructions as early as possible, avoiding headaches and frustration, for new end users and experienced developers alike. -+Technically, executable documentation can be created by using the Sphinx directive `literalinclude `_, which may include whole scripts or parts of them. -+For example, the following directive includes a script fragment detailing a step in compiling the Tezos sources:: +Technically, executable documentation can be created by using the Sphinx directive `literalinclude `_, which may include whole scripts or parts of them. +For example, the following directive includes a script fragment detailing a step in compiling the Tezos sources:: .. literalinclude:: compile-sources.sh :language: shell diff --git a/src/proto_alpha/lib_protocol/tez_repr.ml b/src/proto_alpha/lib_protocol/tez_repr.ml index 1884172f97ce..ddf34a5676a2 100644 --- a/src/proto_alpha/lib_protocol/tez_repr.ml +++ b/src/proto_alpha/lib_protocol/tez_repr.ml @@ -183,7 +183,7 @@ let () = pp opb id) - ~description:("An subtraction of two " ^ id ^ " amounts underflowed") + ~description:("A subtraction of two " ^ id ^ " amounts underflowed") (obj1 (req "amounts" (tup2 encoding encoding))) (function Subtraction_underflow (a, b) -> Some (a, b) | _ -> None) (fun (a, b) -> Subtraction_underflow (a, b)) ; -- GitLab From 92efdcd163c5f7e877fcaaa725c1961fbe835f4c Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 14 Jun 2021 12:26:21 +0200 Subject: [PATCH 4/5] doc: mention how to specify fees in a transfer --- docs/introduction/howtouse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 580e1794f38b..497bac1a2783 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -537,9 +537,9 @@ A baker is more likely to include an operation with lower gas and storage limits because it takes fewer resources to execute so it is in the best interest of the user to pick limits that are as close as possible to the actual use. In this case, you may have to specify some -fees as the baker is expecting some for the resource +fees (using option ``--fee``) as the baker is expecting some for the resource usage. Otherwise, you can force a low fee operation using the -`--force-low-fee`, with the risk that no baker will include it. +``--force-low-fee``, with the risk that no baker will include it. More test contracts can be found in directory :src:`tests_python/contracts_alpha/`. -- GitLab From fc65b33bd8d3ea03b09a9364a763772eca25e846 Mon Sep 17 00:00:00 2001 From: Arvid Jakobsson Date: Tue, 15 Jun 2021 11:06:47 +0200 Subject: [PATCH 5/5] Docs/README: improved description of the :gl: role --- docs/README.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index 7d6efd274562..ab1952bd6b9e 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -75,16 +75,20 @@ Some ad-hoc reference kinds are supported. - ``:opam:`package``` or ``:opam:`text``` points to the package page on ``opam.ocaml.org``, version number is supported (``package.version``) -- ``:gl:```` or ``:opam:`text``` expands and links `GitLab special reference +- ``:gl:`[special gitlab reference]``` or ``:gl:`text <[special gitlab + reference]>``` expands and links `GitLab special references `_, - like for merge requests `tezos/tezos!123`, issues `tezos/tezos#999` - and commits `28309c81`. The default project and namespace is - `tezos/tezos`. In other words, `tezos/tezos#999`, `tezos#999` and - `#999` all refer to the same thing. Currently supports usernames, + like for + merge requests :gl:`tezos/tezos!123` (``:gl:`tezos/tezos!123```), + issues :gl:`tezos/tezos#999` (``:gl:`tezos/tezos#999```) + and + commits :gl:`28309c81` (``:gl:`28309c81```). + The default project and namespace is + ``tezos/tezos``. In other words, ``tezos/tezos#999``, ``tezos#999`` and + ``#999`` all refer to the same thing. Currently supports usernames, projects, issues, merge requests, snippets, milestone ids, commits - and commit ranges. This is implemented in - `docs/_extensions/gitlab_custom_role.py`. + and commit ranges. The implementation of this role is in + :src:`docs/_extensions/gitlab_custom_role.py`. Style guidelines ---------------- -- GitLab