diff --git a/docs/README.rst b/docs/README.rst index fde410deca89298a5ac14c9abd1580c8d85e74cc..ab1952bd6b9e72b0e172325d75839f5724b39d94 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 ---------------- @@ -100,10 +104,11 @@ 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 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. @@ -134,8 +139,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 @@ -230,6 +235,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). diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 118a7d13df7043509cc925a903e364fb805e392c..132840e851a78e6915cc272315ba448162103a0e 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. diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 580e1794f38b6432809fca9aa095d22b528fa966..497bac1a278310ec56ff29276d77b5a05b483911 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/`. diff --git a/src/proto_alpha/lib_protocol/tez_repr.ml b/src/proto_alpha/lib_protocol/tez_repr.ml index 1884172f97ce359e6ca1cfee1548193d68929379..ddf34a5676a2d4f3f1aa6c4cc9bfd70dc0566af1 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)) ;