From a2eb60c713ee538ace46dde5c8ffbe625c1daa86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Schoentgen?= Date: Mon, 12 Feb 2024 23:25:33 +0100 Subject: [PATCH] docs: adopt a new theme: `shibuya` (#3754) --- .readthedocs.yaml | 13 +- Dockerfile | 2 +- README.md | 12 +- docs/_static/css/dark.css | 215 --------------------------- docs/_static/css/toggle.css | 77 ---------- docs/_static/js/toggle.js | 26 ---- docs/built-in-functions.rst | 166 ++++++++++----------- docs/compiler-exceptions.rst | 14 +- docs/compiling-a-contract.rst | 28 ++-- docs/conf.py | 141 +++--------------- docs/constants-and-vars.rst | 6 +- docs/contributing.rst | 2 +- docs/control-structures.rst | 32 ++-- docs/event-logging.rst | 8 +- docs/index.rst | 2 +- docs/interfaces.rst | 24 +-- docs/logo.svg | 4 + docs/natspec.rst | 10 +- docs/scoping-and-declarations.rst | 32 ++-- docs/statements.rst | 16 +- docs/structure-of-a-contract.rst | 24 +-- docs/testing-contracts-brownie.rst | 9 +- docs/testing-contracts-ethtester.rst | 11 +- docs/types.rst | 20 +-- docs/vyper-by-example.rst | 78 +++++----- docs/vyper-logo-transparent.svg | 11 -- examples/tokens/ERC20.vy | 2 +- requirements-docs.txt | 4 +- tox.ini | 4 +- 29 files changed, 286 insertions(+), 707 deletions(-) delete mode 100644 docs/_static/css/dark.css delete mode 100644 docs/_static/css/toggle.css delete mode 100644 docs/_static/js/toggle.js create mode 100644 docs/logo.svg delete mode 100644 docs/vyper-logo-transparent.svg diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 1ad9000f53..e7f5fa079a 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,23 +1,20 @@ -# File: .readthedocs.yaml - version: 2 -# Set the version of Python and other tools you might need build: # TODO: update to `latest` once supported # https://github.com/readthedocs/readthedocs.org/issues/8861 os: ubuntu-22.04 tools: - python: "3.10" + python: "3.11" -# Build from the docs/ directory with Sphinx sphinx: configuration: docs/conf.py -formats: all - +# We can't use "all" because "htmlzip" format is broken for now +formats: + - epub + - pdf -# Optionally declare the Python requirements required to build your docs python: install: - requirements: requirements-docs.txt diff --git a/Dockerfile b/Dockerfile index bc5bb607d6..b4bfa6d3a4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -6,7 +6,7 @@ ARG VCS_REF LABEL org.label-schema.build-date=$BUILD_DATE \ org.label-schema.name="Vyper" \ org.label-schema.description="Vyper is an experimental programming language" \ - org.label-schema.url="https://vyper.readthedocs.io/en/latest/" \ + org.label-schema.url="https://docs.vyperlang.org/en/latest/" \ org.label-schema.vcs-ref=$VCS_REF \ org.label-schema.vcs-url="https://github.com/vyperlang/vyper" \ org.label-schema.vendor="Vyper Team" \ diff --git a/README.md b/README.md index 33c4557cc8..b14b7eaaf0 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Build Status](https://github.com/vyperlang/vyper/workflows/Test/badge.svg)](https://github.com/vyperlang/vyper/actions/workflows/test.yml) -[![Documentation Status](https://readthedocs.org/projects/vyper/badge/?version=latest)](http://vyper.readthedocs.io/en/latest/?badge=latest "ReadTheDocs") +[![Documentation Status](https://readthedocs.org/projects/vyper/badge/?version=latest)](http://docs.vyperlang.org/en/latest/?badge=latest "ReadTheDocs") [![Discord](https://img.shields.io/discord/969926564286459934.svg?label=%23vyper)](https://discord.gg/6tw7PTM7C2) [![PyPI](https://badge.fury.io/py/vyper.svg)](https://pypi.org/project/vyper "PyPI") @@ -13,9 +13,9 @@ [![Language grade: Python](https://github.com/vyperlang/vyper/workflows/CodeQL/badge.svg)](https://github.com/vyperlang/vyper/actions/workflows/codeql.yml) # Getting Started -See [Installing Vyper](http://vyper.readthedocs.io/en/latest/installing-vyper.html) to install vyper. +See [Installing Vyper](http://docs.vyperlang.org/en/latest/installing-vyper.html) to install vyper. See [Tools and Resources](https://github.com/vyperlang/vyper/wiki/Vyper-tools-and-resources) for an additional list of framework and tools with vyper support. -See [Documentation](http://vyper.readthedocs.io/en/latest/index.html) for the documentation and overall design goals of the Vyper language. +See [Documentation](http://docs.vyperlang.org/en/latest/index.html) for the documentation and overall design goals of the Vyper language. See [Learn.Vyperlang.org](https://learn.vyperlang.org/) for **learning Vyper by building a Pokémon game**. See [try.vyperlang.org](https://try.vyperlang.org/) to use Vyper in a hosted jupyter environment! @@ -23,7 +23,7 @@ See [try.vyperlang.org](https://try.vyperlang.org/) to use Vyper in a hosted jup **Note: Vyper is beta software, use with care** # Installation -See the [Vyper documentation](https://vyper.readthedocs.io/en/latest/installing-vyper.html) +See the [Vyper documentation](https://docs.vyperlang.org/en/latest/installing-vyper.html) for build instructions. # Compiling a contract @@ -47,7 +47,7 @@ be a bit behind the latest version found in the master branch of this repository ## Testing (using pytest) -(Complete [installation steps](https://vyper.readthedocs.io/en/latest/installing-vyper.html) first.) +(Complete [installation steps](https://docs.vyperlang.org/en/latest/installing-vyper.html) first.) ```bash make dev-init @@ -75,4 +75,4 @@ To get a call graph from a python profile, https://stackoverflow.com/a/23164271/ * See Issues tab, and feel free to submit your own issues * Add PRs if you discover a solution to an existing issue * For further discussions and questions, post in [Discussions](https://github.com/vyperlang/vyper/discussions) or talk to us on [Discord](https://discord.gg/6tw7PTM7C2) -* For more information, see [Contributing](http://vyper.readthedocs.io/en/latest/contributing.html) +* For more information, see [Contributing](http://docs.vyperlang.org/en/latest/contributing.html) diff --git a/docs/_static/css/dark.css b/docs/_static/css/dark.css deleted file mode 100644 index 158f08e0fc..0000000000 --- a/docs/_static/css/dark.css +++ /dev/null @@ -1,215 +0,0 @@ -/* links */ - -a, -a:visited { - color: #aaddff; -} - - -/* code directives */ - -.method dt, -.class dt, -.data dt, -.attribute dt, -.function dt, -.classmethod dt, -.exception dt, -.descclassname, -.descname { - background-color: #2d2d2d !important; -} - -.descname { - color: inherit !important; -} - -.rst-content dl:not(.docutils) dt { - color: #aaddff; - border-top: solid 3px #525252; - border-left: solid 3px #525252; -} - -em.property { - color: #888888; -} - - -/* tables */ - -.rst-content table.docutils thead { - color: #ddd; -} - -.rst-content table.docutils td { - border: 0px; -} - -.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td { - background-color: #5a5a5a; -} - - -/* inlined code highlights */ - -.xref, -.py-meth, -.rst-content a code { - color: #aaddff !important; - font-weight: normal !important; -} - -.rst-content code { - color: #eee !important; - font-weight: normal !important; -} - -code.literal { - background-color: #2d2d2d !important; - border: 1px solid #6d6d6d !important; -} - -code.docutils.literal.notranslate { - color: #ddd; -} - - -/* code examples */ - -pre { - background: #222; - color: #ddd; - font-size: 150%; - border-color: #333 !important; -} - -.copybutton { - color: #666 !important; - border-color: #333 !important; -} - -.highlight .go, -.highlight .nb, -.highlight .kn { - /* text */ - color: #ddd; - font-weight: normal; -} - -.highlight .o, -.highlight .p { - /* comparators, parentheses */ - color: #bbb; -} - -.highlight .c1 { - /* comments */ - color: #888; -} - -.highlight .bp { - /* self */ - color: #fc3; -} - -.highlight .mf, -.highlight .mi, -.highlight .kc { - /* numbers, booleans */ - color: #c90; -} - -.highlight .gt, -.highlight .nf, -.highlight .fm { - /* functions */ - color: #7cf; -} - -.highlight .nd { - /* decorators */ - color: #f66; -} - -.highlight .k, -.highlight .ow { - /* statements */ - color: #A7F; - font-weight: normal; -} - -.highlight .s2, -.highlight .s1, -.highlight .nt { - /* strings */ - color: #5d6; -} - - -/* notes, warnings, hints */ - -.hint .admonition-title { - background: #2aa87c !important; -} - -.warning .admonition-title { - background: #cc4444 !important; -} - -.admonition-title { - background: #3a7ca8 !important; -} - -.admonition, -.note { - background-color: #2d2d2d !important; -} - - -/* table of contents */ - -.wy-body-for-nav { - background-color: rgb(26, 28, 29); -} - -.wy-nav-content-wrap { - background-color: rgba(0, 0, 0, 0.6) !important; -} - -.sidebar { - background-color: #191919 !important; -} - -.sidebar-title { - background-color: #2b2b2b !important; -} - -.wy-menu-vertical a { - color: #ddd; -} - -.wy-menu-vertical code.docutils.literal.notranslate { - color: #404040; - background: none !important; - border: none !important; -} - -.wy-nav-content { - background: #3c3c3c; - color: #dddddd; -} - -.wy-menu-vertical li.on a, -.wy-menu-vertical li.current>a { - background: #a3a3a3; - border-bottom: 0px !important; - border-top: 0px !important; -} - -.wy-menu-vertical li.current { - background: #b3b3b3; -} - -.toc-backref { - color: grey !important; -} \ No newline at end of file diff --git a/docs/_static/css/toggle.css b/docs/_static/css/toggle.css deleted file mode 100644 index ebbd0658a1..0000000000 --- a/docs/_static/css/toggle.css +++ /dev/null @@ -1,77 +0,0 @@ -input[type=checkbox] { - visibility: hidden; - height: 0; - width: 0; - margin: 0; -} - -.rst-versions .rst-current-version { - padding: 10px; - display: flex; - justify-content: space-between; -} - -.rst-versions .rst-current-version .fa-book, -.rst-versions .rst-current-version .fa-v, -.rst-versions .rst-current-version .fa-caret-down { - height: 24px; - line-height: 24px; - vertical-align: middle; -} - -.rst-versions .rst-current-version .fa-element { - width: 80px; - text-align: center; -} - -.rst-versions .rst-current-version .fa-book { - text-align: left; -} - -.rst-versions .rst-current-version .fa-v { - color: #27AE60; - text-align: right; -} - -label { - margin: 0 auto; - display: inline-block; - justify-content: center; - align-items: right; - border-radius: 100px; - position: relative; - cursor: pointer; - text-indent: -9999px; - width: 50px; - height: 21px; - background: #000; -} - -label:after { - border-radius: 50%; - position: absolute; - content: ''; - background: #fff; - width: 15px; - height: 15px; - top: 3px; - left: 3px; - transition: ease-in-out 200ms; -} - -input:checked+label { - background: #3a7ca8; -} - -input:checked+label:after { - left: calc(100% - 5px); - transform: translateX(-100%); -} - -html.transition, -html.transition *, -html.transition *:before, -html.transition *:after { - transition: ease-in-out 200ms !important; - transition-delay: 0 !important; -} \ No newline at end of file diff --git a/docs/_static/js/toggle.js b/docs/_static/js/toggle.js deleted file mode 100644 index df131042b5..0000000000 --- a/docs/_static/js/toggle.js +++ /dev/null @@ -1,26 +0,0 @@ -document.addEventListener('DOMContentLoaded', function() { - - var checkbox = document.querySelector('input[name=mode]'); - - function toggleCssMode(isDay) { - var mode = (isDay ? "Day" : "Night"); - localStorage.setItem("css-mode", mode); - - var darksheet = $('link[href="_static/css/dark.css"]')[0].sheet; - darksheet.disabled = isDay; - } - - if (localStorage.getItem("css-mode") == "Day") { - toggleCssMode(true); - checkbox.setAttribute('checked', true); - } - - checkbox.addEventListener('change', function() { - document.documentElement.classList.add('transition'); - window.setTimeout(() => { - document.documentElement.classList.remove('transition'); - }, 1000) - toggleCssMode(this.checked); - }) - -}); \ No newline at end of file diff --git a/docs/built-in-functions.rst b/docs/built-in-functions.rst index 45cf9ec8c2..afb64e71ca 100644 --- a/docs/built-in-functions.rst +++ b/docs/built-in-functions.rst @@ -14,14 +14,14 @@ Bitwise Operations Perform a "bitwise and" operation. Each bit of the output is 1 if the corresponding bit of ``x`` AND of ``y`` is 1, otherwise it is 0. - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: uint256, y: uint256) -> uint256: return bitwise_and(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(31337, 8008135) 12353 @@ -34,14 +34,14 @@ Bitwise Operations Return the bitwise complement of ``x`` - the number you get by switching each 1 for a 0 and each 0 for a 1. - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: uint256) -> uint256: return bitwise_not(x) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(0) 115792089237316195423570985008687907853269984665640564039457584007913129639935 @@ -54,14 +54,14 @@ Bitwise Operations Perform a "bitwise or" operation. Each bit of the output is 0 if the corresponding bit of ``x`` AND of ``y`` is 0, otherwise it is 1. - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: uint256, y: uint256) -> uint256: return bitwise_or(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(31337, 8008135) 8027119 @@ -74,14 +74,14 @@ Bitwise Operations Perform a "bitwise exclusive or" operation. Each bit of the output is the same as the corresponding bit in ``x`` if that bit in ``y`` is 0, and it is the complement of the bit in ``x`` if that bit in ``y`` is 1. - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: uint256, y: uint256) -> uint256: return bitwise_xor(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(31337, 8008135) 8014766 @@ -94,14 +94,14 @@ Bitwise Operations Return ``x`` with the bits shifted ``_shift`` places. A positive ``_shift`` value equals a left shift, a negative value is a right shift. - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: uint256, y: int128) -> uint256: return shift(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(2, 8) 512 @@ -144,7 +144,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui Returns the address of the newly created proxy contract. If the create operation fails (for instance, in the case of a ``CREATE2`` collision), execution will revert. - .. code-block:: python + .. code-block:: vyper @external def foo(target: address) -> address: @@ -173,7 +173,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui Returns the address of the created contract. If the create operation fails (for instance, in the case of a ``CREATE2`` collision), execution will revert. If there is no code at ``target``, execution will revert. - .. code-block:: python + .. code-block:: vyper @external def foo(target: address) -> address: @@ -197,7 +197,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui Returns the address of the created contract. If the create operation fails (for instance, in the case of a ``CREATE2`` collision), execution will revert. If ``code_offset >= target.codesize`` (ex. if there is no code at ``target``), execution will revert. - .. code-block:: python + .. code-block:: vyper @external def foo(blueprint: address) -> address: @@ -213,7 +213,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui It is recommended to deploy blueprints with the ERC-5202 preamble ``0xFE7100`` to guard them from being called as regular contracts. This is particularly important for factories where the constructor has side effects (including ``SELFDESTRUCT``!), as those could get executed by *anybody* calling the blueprint contract directly. The ``code_offset=`` kwarg is provided to enable this pattern: - .. code-block:: python + .. code-block:: vyper @external def foo(blueprint: address) -> address: @@ -241,7 +241,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui Returns ``success`` in a tuple with return value if ``revert_on_failure`` is set to ``False``. - .. code-block:: python + .. code-block:: vyper @external @payable @@ -276,7 +276,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui * ``topics``: List of ``bytes32`` log topics. The length of this array determines which opcode is used. * ``data``: Unindexed event data to include in the log. May be given as ``Bytes`` or ``bytes32``. - .. code-block:: python + .. code-block:: vyper @external def foo(_topic: bytes32, _data: Bytes[100]): @@ -288,7 +288,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui * ``data``: Data representing the error message causing the revert. - .. code-block:: python + .. code-block:: vyper @external def foo(_data: Bytes[100]): @@ -308,7 +308,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui This function has been deprecated from version 0.3.8 onwards. The underlying opcode will eventually undergo breaking changes, and its use is not recommended. - .. code-block:: python + .. code-block:: vyper @external def do_the_needful(): @@ -326,7 +326,7 @@ Vyper has three built-ins for contract creation; all three contract creation bui The amount to send is always specified in ``wei``. - .. code-block:: python + .. code-block:: vyper @external def foo(_receiver: address, _amount: uint256, gas: uint256): @@ -339,14 +339,14 @@ Cryptography Take two points on the Alt-BN128 curve and add them together. - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: uint256[2], y: uint256[2]) -> uint256[2]: return ecadd(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo([1, 2], [1, 2]) [ @@ -361,14 +361,14 @@ Cryptography * ``point``: Point to be multiplied * ``scalar``: Scalar value - .. code-block:: python + .. code-block:: vyper @external @view def foo(point: uint256[2], scalar: uint256) -> uint256[2]: return ecmul(point, scalar) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo([1, 2], 3) [ @@ -390,7 +390,7 @@ Cryptography Prior to Vyper ``0.3.10``, the ``ecrecover`` function could return an undefined (possibly nonzero) value for invalid inputs to ``ecrecover``. For more information, please see `GHSA-f5x6-7qgp-jhf3 `_. - .. code-block:: python + .. code-block:: vyper @external @view @@ -402,7 +402,7 @@ Cryptography @view def foo(hash: bytes32, v: uint256, r:uint256, s:uint256) -> address: return ecrecover(hash, v, r, s) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo('0x6c9c5e133b8aafb2ea74f524a5263495e7ae5701c7248805f7b511d973dc7055', 28, @@ -417,14 +417,14 @@ Cryptography * ``_value``: Value to hash. Can be a ``String``, ``Bytes``, or ``bytes32``. - .. code-block:: python + .. code-block:: vyper @external @view def foo(_value: Bytes[100]) -> bytes32 return keccak256(_value) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(b"potato") 0x9e159dfcfe557cc1ca6c716e87af98fdcb94cd8c832386d0429b2b7bec02754f @@ -435,14 +435,14 @@ Cryptography * ``_value``: Value to hash. Can be a ``String``, ``Bytes``, or ``bytes32``. - .. code-block:: python + .. code-block:: vyper @external @view def foo(_value: Bytes[100]) -> bytes32 return sha256(_value) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(b"potato") 0xe91c254ad58860a02c788dfb5c1a65d6a8846ab1dc649631c7db16fef4af2dec @@ -456,14 +456,14 @@ Data Manipulation If the input arguments are ``String`` the return type is ``String``. Otherwise the return type is ``Bytes``. - .. code-block:: python + .. code-block:: vyper @external @view def foo(a: String[5], b: String[5], c: String[5]) -> String[100]: return concat(a, " ", b, " ", c, "!") - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo("why","hello","there") "why hello there!" @@ -487,14 +487,14 @@ Data Manipulation Returns the string representation of ``value``. - .. code-block:: python + .. code-block:: vyper @external @view def foo(b: uint256) -> String[78]: return uint2str(b) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(420) "420" @@ -509,14 +509,14 @@ Data Manipulation Returns a value of the type specified by ``output_type``. - .. code-block:: python + .. code-block:: vyper @external @view def foo(b: Bytes[32]) -> address: return extract32(b, 0, output_type=address) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo("0x0000000000000000000000009f8F72aA9304c8B593d555F12eF6589cC3A579A2") "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2" @@ -531,14 +531,14 @@ Data Manipulation If the value being sliced is a ``Bytes`` or ``bytes32``, the return type is ``Bytes``. If it is a ``String``, the return type is ``String``. - .. code-block:: python + .. code-block:: vyper @external @view def foo(s: String[32]) -> String[5]: return slice(s, 4, 5) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo("why hello! how are you?") "hello" @@ -552,14 +552,14 @@ Math * ``value``: Integer to return the absolute value of - .. code-block:: python + .. code-block:: vyper @external @view def foo(value: int256) -> int256: return abs(value) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(-31337) 31337 @@ -570,14 +570,14 @@ Math * ``value``: Decimal value to round up - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: decimal) -> int256: return ceil(x) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(3.1337) 4 @@ -588,14 +588,14 @@ Math * ``typename``: Name of the decimal type (currently only ``decimal``) - .. code-block:: python + .. code-block:: vyper @external @view def foo() -> decimal: return epsilon(decimal) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo() Decimal('1E-10') @@ -606,14 +606,14 @@ Math * ``value``: Decimal value to round down - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: decimal) -> int256: return floor(x) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(3.1337) 3 @@ -622,14 +622,14 @@ Math Return the greater value of ``a`` and ``b``. The input values may be any numeric type as long as they are both of the same type. The output value is of the same type as the input values. - .. code-block:: python + .. code-block:: vyper @external @view def foo(a: uint256, b: uint256) -> uint256: return max(a, b) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(23, 42) 42 @@ -638,14 +638,14 @@ Math Returns the maximum value of the numeric type specified by ``type_`` (e.g., ``int128``, ``uint256``, ``decimal``). - .. code-block:: python + .. code-block:: vyper @external @view def foo() -> int256: return max_value(int256) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo() 57896044618658097711785492504343953926634992332820282019728792003956564819967 @@ -654,14 +654,14 @@ Math Returns the lesser value of ``a`` and ``b``. The input values may be any numeric type as long as they are both of the same type. The output value is of the same type as the input values. - .. code-block:: python + .. code-block:: vyper @external @view def foo(a: uint256, b: uint256) -> uint256: return min(a, b) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(23, 42) 23 @@ -670,14 +670,14 @@ Math Returns the minimum value of the numeric type specified by ``type_`` (e.g., ``int128``, ``uint256``, ``decimal``). - .. code-block:: python + .. code-block:: vyper @external @view def foo() -> int256: return min_value(int256) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo() -57896044618658097711785492504343953926634992332820282019728792003956564819968 @@ -688,14 +688,14 @@ Math This method is used to perform exponentiation without overflow checks. - .. code-block:: python + .. code-block:: vyper @external @view def foo(a: uint256, b: uint256) -> uint256: return pow_mod256(a, b) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(2, 3) 8 @@ -706,14 +706,14 @@ Math Return the square root of the provided decimal number, using the Babylonian square root algorithm. - .. code-block:: python + .. code-block:: vyper @external @view def foo(d: decimal) -> decimal: return sqrt(d) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(9.0) 3.0 @@ -722,14 +722,14 @@ Math Return the (integer) square root of the provided integer number, using the Babylonian square root algorithm. The rounding mode is to round down to the nearest integer. For instance, ``isqrt(101) == 10``. - .. code-block:: python + .. code-block:: vyper @external @view def foo(x: uint256) -> uint256: return isqrt(x) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(101) 10 @@ -738,14 +738,14 @@ Math Return the modulo of ``(a + b) % c``. Reverts if ``c == 0``. As this built-in function is intended to provides access to the underlying ``ADDMOD`` opcode, all intermediate calculations of this operation are not subject to the ``2 ** 256`` modulo according to the EVM specifications. - .. code-block:: python + .. code-block:: vyper @external @view def foo(a: uint256, b: uint256, c: uint256) -> uint256: return uint256_addmod(a, b, c) - .. code-block:: python + .. code-block:: vyper >>> (6 + 13) % 8 3 @@ -756,14 +756,14 @@ Math Return the modulo from ``(a * b) % c``. Reverts if ``c == 0``. As this built-in function is intended to provides access to the underlying ``MULMOD`` opcode, all intermediate calculations of this operation are not subject to the ``2 ** 256`` modulo according to the EVM specifications. - .. code-block:: python + .. code-block:: vyper @external @view def foo(a: uint256, b: uint256, c: uint256) -> uint256: return uint256_mulmod(a, b, c) - .. code-block:: python + .. code-block:: vyper >>> (11 * 2) % 5 2 @@ -774,7 +774,7 @@ Math Add ``x`` and ``y``, without checking for overflow. ``x`` and ``y`` must both be integers of the same type. If the result exceeds the bounds of the input type, it will be wrapped. - .. code-block:: python + .. code-block:: vyper @external @view @@ -787,7 +787,7 @@ Math return unsafe_add(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(1, 1) 2 @@ -805,7 +805,7 @@ Math Subtract ``x`` and ``y``, without checking for overflow. ``x`` and ``y`` must both be integers of the same type. If the result underflows the bounds of the input type, it will be wrapped. - .. code-block:: python + .. code-block:: vyper @external @view @@ -818,7 +818,7 @@ Math return unsafe_sub(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(4, 3) 1 @@ -837,7 +837,7 @@ Math Multiply ``x`` and ``y``, without checking for overflow. ``x`` and ``y`` must both be integers of the same type. If the result exceeds the bounds of the input type, it will be wrapped. - .. code-block:: python + .. code-block:: vyper @external @view @@ -850,7 +850,7 @@ Math return unsafe_mul(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(1, 1) 1 @@ -872,7 +872,7 @@ Math Divide ``x`` and ``y``, without checking for division-by-zero. ``x`` and ``y`` must both be integers of the same type. If the denominator is zero, the result will (following EVM semantics) be zero. - .. code-block:: python + .. code-block:: vyper @external @view @@ -885,7 +885,7 @@ Math return unsafe_div(x, y) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(1, 1) 1 @@ -910,14 +910,14 @@ Utilities * ``_value``: Value for the ether unit. Any numeric type may be used, however the value cannot be negative. * ``unit``: Ether unit name (e.g. ``"wei"``, ``"ether"``, ``"gwei"``, etc.) indicating the denomination of ``_value``. Must be given as a literal string. - .. code-block:: python + .. code-block:: vyper @external @view def foo(s: String[32]) -> uint256: return as_wei_value(1.337, "ether") - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo(1) 1337000000000000000 @@ -930,14 +930,14 @@ Utilities The EVM only provides access to the most recent 256 blocks. This function reverts if the block number is greater than or equal to the current block number or more than 256 blocks behind the current block. - .. code-block:: python + .. code-block:: vyper @external @view def foo() -> bytes32: return blockhash(block.number - 16) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo() 0xf3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 @@ -948,7 +948,7 @@ Utilities * ``typename``: Name of the type, except ``HashMap[_KeyType, _ValueType]`` - .. code-block:: python + .. code-block:: vyper @external @view @@ -959,14 +959,14 @@ Utilities Return the length of a given ``Bytes``, ``String`` or ``DynArray[_Type, _Integer]``. - .. code-block:: python + .. code-block:: vyper @external @view def foo(s: String[32]) -> uint256: return len(s) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo("hello") 5 @@ -980,14 +980,14 @@ Utilities Returns a value of the type specified by ``output_type``. - .. code-block:: python + .. code-block:: vyper @external @view def foo() -> Bytes[4]: return method_id('transfer(address,uint256)', output_type=Bytes[4]) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo() 0xa9059cbb @@ -1003,7 +1003,7 @@ Utilities Returns a bytestring whose max length is determined by the arguments. For example, encoding a ``Bytes[32]`` results in a ``Bytes[64]`` (first word is the length of the bytestring variable). - .. code-block:: python + .. code-block:: vyper @external @view @@ -1012,7 +1012,7 @@ Utilities y: Bytes[32] = b"234" return _abi_encode(x, y, method_id=method_id("foo()")) - .. code-block:: python + .. code-block:: vyper >>> ExampleContract.foo().hex() "c2985578" @@ -1033,7 +1033,7 @@ Utilities Returns the decoded value(s), with type as specified by `output_type`. - .. code-block:: python + .. code-block:: vyper @external @view diff --git a/docs/compiler-exceptions.rst b/docs/compiler-exceptions.rst index 395ce448ed..29b8b5c96e 100644 --- a/docs/compiler-exceptions.rst +++ b/docs/compiler-exceptions.rst @@ -58,7 +58,7 @@ of the error within the code: Raises when no valid type can be found for a literal value. - .. code-block:: python + .. code-block:: vyper @external def foo(): @@ -70,7 +70,7 @@ of the error within the code: Raises when using an invalid operator for a given type. - .. code-block:: python + .. code-block:: vyper @external def foo(): @@ -82,7 +82,7 @@ of the error within the code: Raises on an invalid reference to an existing definition. - .. code-block:: python + .. code-block:: vyper baz: int128 @@ -96,7 +96,7 @@ of the error within the code: Raises when using an invalid literal value for the given type. - .. code-block:: python + .. code-block:: vyper @external def foo(): @@ -132,7 +132,7 @@ of the error within the code: Raises when attempting to access ``msg.value`` from within a function that has not been marked as ``@payable``. - .. code-block:: python + .. code-block:: vyper @public def _foo(): @@ -174,7 +174,7 @@ of the error within the code: Raises when attempting to perform an action between two or more objects with known, dislike types. - .. code-block:: python + .. code-block:: vyper @external def foo(: @@ -215,7 +215,7 @@ CompilerPanic .. py:exception:: CompilerPanic - :: + .. code:: shell $ vyper v.vy Error compiling: v.vy diff --git a/docs/compiling-a-contract.rst b/docs/compiling-a-contract.rst index b529d1efb1..2b069c2add 100644 --- a/docs/compiling-a-contract.rst +++ b/docs/compiling-a-contract.rst @@ -20,20 +20,20 @@ vyper To compile a contract: -:: +.. code:: shell $ vyper yourFileName.vy Include the ``-f`` flag to specify which output formats to return. Use ``vyper --help`` for a full list of output options. -:: +.. code:: shell $ vyper -f abi,bytecode,bytecode_runtime,ir,asm,source_map,method_identifiers yourFileName.vy The ``-p`` flag allows you to set a root path that is used when searching for interface files to import. If none is given, it will default to the current working directory. See :ref:`searching_for_imports` for more information. -:: +.. code:: shell $ vyper -p yourProject yourProject/yourFileName.vy @@ -45,7 +45,7 @@ Storage Layout To display the default storage layout for a contract: -:: +.. code:: shell $ vyper -f layout yourFileName.vy @@ -53,7 +53,7 @@ This outputs a JSON object detailing the locations for all state variables as de To override the default storage layout for a contract: -:: +.. code:: shell $ vyper --storage-layout-file storageLayout.json yourFileName.vy @@ -69,19 +69,19 @@ vyper-json To compile from JSON supplied via ``stdin``: -:: +.. code:: shell $ vyper-json To compile from a JSON file: -:: +.. code:: shell $ vyper-json yourProject.json By default, the output is sent to ``stdout``. To redirect to a file, use the ``-o`` flag: -:: +.. code:: shell $ vyper-json -o compiled.json @@ -143,7 +143,7 @@ When you compile your contract code, you can specify the target Ethereum Virtual For instance, the adding the following pragma to a contract indicates that it should be compiled for the "shanghai" fork of the EVM. -.. code-block:: python +.. code-block:: vyper #pragma evm-version shanghai @@ -153,13 +153,13 @@ For instance, the adding the following pragma to a contract indicates that it sh When compiling via the ``vyper`` CLI, you can specify the EVM version option using the ``--evm-version`` flag: -:: +.. code:: shell $ vyper --evm-version [VERSION] When using the JSON interface, you can include the ``"evmVersion"`` key within the ``"settings"`` field: -.. code-block:: javascript +.. code-block:: json { "settings": { @@ -200,8 +200,6 @@ The following is a list of supported EVM versions, and changes in the compiler i - The ``MCOPY`` opcode will be generated automatically by the compiler for most memory operations. - - Compiler Input and Output JSON Description ========================================== @@ -216,7 +214,7 @@ Input JSON Description The following example describes the expected input format of ``vyper-json``. Comments are of course not permitted and used here *only for explanatory purposes*. -.. code-block:: javascript +.. code-block:: json { // Required: Source code language. Must be set to "Vyper". @@ -294,7 +292,7 @@ Output JSON Description The following example describes the output format of ``vyper-json``. Comments are of course not permitted and used here *only for explanatory purposes*. -.. code-block:: javascript +.. code-block:: json { // The compiler version used to generate the JSON diff --git a/docs/conf.py b/docs/conf.py index 5dc1eee8f5..99ffe35a63 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,57 +1,12 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# # Vyper documentation build configuration file, created by # sphinx-quickstart on Wed Jul 26 11:18:29 2017. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) -from recommonmark.parser import CommonMarkParser - -# TO DO - Create and Implement Vyper Lexer -# def setup(sphinx): -# sys.path.insert(0, os.path.abspath('./utils')) -# from SolidityLexer import SolidityLexer -# sphinx.add_lexer('Python', SolidityLexer()) - - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ - "sphinx.ext.autodoc", + "sphinx_copybutton", "sphinx.ext.intersphinx", ] -# Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -source_suffix = [".rst", ".md"] - -# The master toctree document. master_doc = "toctree" # General information about the project. @@ -59,68 +14,31 @@ copyright = "2017-2024 CC-BY-4.0 Vyper Team" author = "Vyper Team (originally created by Vitalik Buterin)" -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = "" -# The full version, including alpha/beta/rc tags. -release = "" - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = "python" - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - +language = "vyper" # -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - -html_css_files = ["css/toggle.css", "css/dark.css"] - -html_js_files = ["js/toggle.js"] - -html_logo = "vyper-logo-transparent.svg" - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - +html_theme = "shibuya" +html_theme_options = { + "accent_color": "purple", + "twitter_creator": "vyperlang", + "twitter_site": "vyperlang", + "twitter_url": "https://twitter.com/vyperlang", + "github_url": "https://github.com/vyperlang", +} +html_favicon = "logo.svg" +html_logo = "logo.svg" + +# For the "Edit this page ->" link +html_context = { + "source_type": "github", + "source_user": "vyperlang", + "source_repo": "vyper", +} # -- Options for HTMLHelp output ------------------------------------------ @@ -130,21 +48,6 @@ # -- Options for LaTeX output --------------------------------------------- -latex_elements: dict = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). @@ -153,7 +56,7 @@ master_doc, "Vyper.tex", "Vyper Documentation", - "Vyper Team (originally created by Vitalik Buterin)", + author, "manual", ), ] @@ -183,10 +86,6 @@ ), ] -source_parsers = { - ".md": CommonMarkParser, -} - intersphinx_mapping = { "brownie": ("https://eth-brownie.readthedocs.io/en/stable", None), "pytest": ("https://docs.pytest.org/en/latest/", None), diff --git a/docs/constants-and-vars.rst b/docs/constants-and-vars.rst index 7f9c1408c5..00ce7a8ccc 100644 --- a/docs/constants-and-vars.rst +++ b/docs/constants-and-vars.rst @@ -56,7 +56,7 @@ Accessing State Variables ``self`` is used to access a contract's :ref:`state variables`, as shown in the following example: -.. code-block:: python +.. code-block:: vyper state_var: uint256 @@ -76,7 +76,7 @@ Calling Internal Functions ``self`` is also used to call :ref:`internal functions` within a contract: -.. code-block:: python +.. code-block:: vyper @internal def _times_two(amount: uint256) -> uint256: @@ -93,7 +93,7 @@ Custom Constants Custom constants can be defined at a global level in Vyper. To define a constant, make use of the ``constant`` keyword. -.. code-block:: python +.. code-block:: vyper TOTAL_SUPPLY: constant(uint256) = 10000000 total_supply: public(uint256) diff --git a/docs/contributing.rst b/docs/contributing.rst index 221600f930..55b2694424 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -5,7 +5,7 @@ Contributing Help is always appreciated! -To get started, you can try `installing Vyper `_ in order to familiarize +To get started, you can try `installing Vyper `_ in order to familiarize yourself with the components of Vyper and the build process. Also, it may be useful to become well-versed at writing smart-contracts in Vyper. diff --git a/docs/control-structures.rst b/docs/control-structures.rst index 14202cbae7..a0aa927261 100644 --- a/docs/control-structures.rst +++ b/docs/control-structures.rst @@ -10,7 +10,7 @@ Functions Functions are executable units of code within a contract. Functions may only be declared within a contract's :ref:`module scope `. -.. code-block:: python +.. code-block:: vyper @external def bid(): @@ -30,7 +30,7 @@ External Functions External functions (marked with the ``@external`` decorator) are a part of the contract interface and may only be called via transactions or from other contracts. -.. code-block:: python +.. code-block:: vyper @external def add_seven(a: int128) -> int128: @@ -52,7 +52,7 @@ Internal Functions Internal functions (marked with the ``@internal`` decorator) are only accessible from other functions within the same contract. They are called via the :ref:`self` object: -.. code-block:: python +.. code-block:: vyper @internal def _times_two(amount: uint256, two: uint256 = 2) -> uint256: @@ -77,7 +77,7 @@ You can optionally declare a function's mutability by using a :ref:`decorator )`` decorator places a lock on a function, and all functions with the same ```` value. An attempt by an external contract to call back into any of these functions causes the transaction to revert. -.. code-block:: python +.. code-block:: vyper @external @nonreentrant("lock") @@ -133,7 +133,7 @@ This function is always named ``__default__``. It must be annotated with ``@exte If the function is annotated as ``@payable``, this function is executed whenever the contract is sent Ether (without data). This is why the default function cannot accept arguments - it is a design decision of Ethereum to make no differentiation between sending ether to a contract or a user address. -.. code-block:: python +.. code-block:: vyper event Payment: amount: uint256 @@ -169,7 +169,7 @@ The ``__init__`` Function ``__init__`` is a special initialization function that may only be called at the time of deploying a contract. It can be used to set initial values for storage variables. A common use case is to set an ``owner`` variable with the creator the contract: -.. code-block:: python +.. code-block:: vyper owner: address @@ -202,7 +202,7 @@ Decorator Description The ``if`` statement is a control flow construct used for conditional execution: -.. code-block:: python +.. code-block:: vyper if CONDITION: ... @@ -213,7 +213,7 @@ Note that unlike Python, Vyper does not allow implicit conversion from non-boole You can also include ``elif`` and ``else`` statements, to add more conditional statements and a body that executes when the conditionals are false: -.. code-block:: python +.. code-block:: vyper if CONDITION: ... @@ -227,7 +227,7 @@ You can also include ``elif`` and ``else`` statements, to add more conditional s The ``for`` statement is a control flow construct used to iterate over a value: -.. code-block:: python +.. code-block:: vyper for i in : ... @@ -239,7 +239,7 @@ Array Iteration You can use ``for`` to iterate through the values of any array variable: -.. code-block:: python +.. code-block:: vyper foo: int128[3] = [4, 23, 42] for i in foo: @@ -249,7 +249,7 @@ In the above, example, the loop executes three times with ``i`` assigned the val You can also iterate over a literal array, as long as a common type can be determined for each item in the array: -.. code-block:: python +.. code-block:: vyper for i in [4, 23, 42]: ... @@ -264,14 +264,14 @@ Range Iteration Ranges are created using the ``range`` function. The following examples are valid uses of ``range``: -.. code-block:: python +.. code-block:: vyper for i in range(STOP): ... ``STOP`` is a literal integer greater than zero. ``i`` begins as zero and increments by one until it is equal to ``STOP``. -.. code-block:: python +.. code-block:: vyper for i in range(stop, bound=N): ... @@ -280,7 +280,7 @@ Here, ``stop`` can be a variable with integer type, greater than zero. ``N`` mus Another use of range can be with ``START`` and ``STOP`` bounds. -.. code-block:: python +.. code-block:: vyper for i in range(START, STOP): ... @@ -291,7 +291,7 @@ Finally, it is possible to use ``range`` with runtime `start` and `stop` values In this case, Vyper checks at runtime that `end - start <= bound`. ``N`` must be a compile-time constant. -.. code-block:: python +.. code-block:: vyper for i in range(start, end, bound=N): ... diff --git a/docs/event-logging.rst b/docs/event-logging.rst index 904b179e70..4f350d6459 100644 --- a/docs/event-logging.rst +++ b/docs/event-logging.rst @@ -10,7 +10,7 @@ Example of Logging This example is taken from the `sample ERC20 contract `_ and shows the basic flow of event logging: -.. code-block:: python +.. code-block:: vyper # Events of the token. event Transfer: @@ -59,7 +59,7 @@ Declaring Events Let's look at an event declaration in more detail. -.. code-block:: python +.. code-block:: vyper event Transfer: sender: indexed(address) @@ -81,7 +81,7 @@ Event declarations look similar to struct declarations, containing one or more a Note that the first topic of a log record consists of the signature of the name of the event that occurred, including the types of its parameters. It is also possible to create an event with no arguments. In this case, use the ``pass`` statement: -.. code-block:: python +.. code-block:: vyper event Foo: pass @@ -92,7 +92,7 @@ Once an event is declared, you can log (send) events. You can send events as man Logging events is done using the ``log`` statement: -.. code-block:: python +.. code-block:: vyper log Transfer(msg.sender, _to, _amount) diff --git a/docs/index.rst b/docs/index.rst index 69d818cd69..8ee48cdb83 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -.. image:: vyper-logo-transparent.svg +.. image:: logo.svg :width: 140px :alt: Vyper logo :align: center diff --git a/docs/interfaces.rst b/docs/interfaces.rst index ab220272d8..803b9daf18 100644 --- a/docs/interfaces.rst +++ b/docs/interfaces.rst @@ -12,7 +12,7 @@ Interfaces can be added to contracts either through inline definition, or by imp The ``interface`` keyword is used to define an inline external interface: -.. code-block:: python +.. code-block:: vyper interface FooBar: def calculate() -> uint256: view @@ -20,7 +20,7 @@ The ``interface`` keyword is used to define an inline external interface: The defined interface can then be used to make external calls, given a contract address: -.. code-block:: python +.. code-block:: vyper @external def test(foobar: FooBar): @@ -28,7 +28,7 @@ The defined interface can then be used to make external calls, given a contract The interface name can also be used as a type annotation for storage variables. You then assign an address value to the variable to access that interface. Note that casting an address to an interface is possible, e.g. ``FooBar()``: -.. code-block:: python +.. code-block:: vyper foobar_contract: FooBar @@ -42,7 +42,7 @@ The interface name can also be used as a type annotation for storage variables. Specifying ``payable`` or ``nonpayable`` annotation indicates that the call made to the external contract will be able to alter storage, whereas the ``view`` ``pure`` call will use a ``STATICCALL`` ensuring no storage can be altered during execution. Additionally, ``payable`` allows non-zero value to be sent along with the call. -.. code-block:: python +.. code-block:: vyper interface FooBar: def calculate() -> uint256: pure @@ -70,7 +70,7 @@ Keyword Description The ``default_return_value`` parameter can be used to handle ERC20 tokens affected by the missing return value bug in a way similar to OpenZeppelin's ``safeTransfer`` for Solidity: -.. code-block:: python +.. code-block:: vyper ERC20(USDT).transfer(msg.sender, 1, default_return_value=True) # returns True ERC20(USDT).transfer(msg.sender, 1) # reverts because nothing returned @@ -86,7 +86,7 @@ Interfaces are imported with ``import`` or ``from ... import`` statements. Imported interfaces are written using standard Vyper syntax. The body of each function is ignored when the interface is imported. If you are defining a standalone interface, it is normally specified by using a ``pass`` statement: -.. code-block:: python +.. code-block:: vyper @external def test1(): @@ -98,7 +98,7 @@ Imported interfaces are written using standard Vyper syntax. The body of each fu You can also import a fully implemented contract and Vyper will automatically convert it to an interface. It is even possible for a contract to import itself to gain access to its own interface. -.. code-block:: python +.. code-block:: vyper import greeter as Greeter @@ -118,7 +118,7 @@ Imports via ``import`` With absolute ``import`` statements, you **must** include an alias as a name for the imported package. In the following example, failing to include ``as Foo`` will raise a compile error: -.. code-block:: python +.. code-block:: vyper import contract.foo as Foo @@ -127,7 +127,7 @@ Imports via ``from ... import`` Using ``from`` you can perform both absolute and relative imports. You may optionally include an alias - if you do not, the name of the interface will be the same as the file. -.. code-block:: python +.. code-block:: vyper # without an alias from contract import foo @@ -137,7 +137,7 @@ Using ``from`` you can perform both absolute and relative imports. You may optio Relative imports are possible by prepending dots to the contract name. A single leading dot indicates a relative import starting with the current package. Two leading dots indicate a relative import from the parent of the current package: -.. code-block:: python +.. code-block:: vyper from . import foo from ..interfaces import baz @@ -162,7 +162,7 @@ Built-in Interfaces Vyper includes common built-in interfaces such as `ERC20 `_ and `ERC721 `_. These are imported from ``ethereum.ercs``: -.. code-block:: python +.. code-block:: vyper from ethereum.ercs import ERC20 @@ -175,7 +175,7 @@ Implementing an Interface You can define an interface for your contract with the ``implements`` statement: -.. code-block:: python +.. code-block:: vyper import an_interface as FooBarInterface diff --git a/docs/logo.svg b/docs/logo.svg new file mode 100644 index 0000000000..d2c666074a --- /dev/null +++ b/docs/logo.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/natspec.rst b/docs/natspec.rst index a6c2d932e4..90ad5d39b4 100644 --- a/docs/natspec.rst +++ b/docs/natspec.rst @@ -17,7 +17,7 @@ Vyper supports structured documentation for contracts and external functions usi The compiler does not parse docstrings of internal functions. You are welcome to NatSpec in comments for internal functions, however they are not processed or included in the compiler output. -.. code-block:: python +.. code-block:: vyper """ @title A simulator for Bug Bunny, the most famous Rabbit @@ -72,16 +72,16 @@ When parsed by the compiler, documentation such as the one from the above exampl If the above contract is saved as ``carrots.vy`` then you can generate the documentation using: -.. code:: +.. code:: shell - vyper -f userdoc,devdoc carrots.vy + $ vyper -f userdoc,devdoc carrots.vy User Documentation ------------------ The above documentation will produce the following user documentation JSON as output: -.. code-block:: javascript +.. code-block:: json { "methods": { @@ -102,7 +102,7 @@ Developer Documentation Apart from the user documentation file, a developer documentation JSON file should also be produced and should look like this: -.. code-block:: javascript +.. code-block:: json { "author": "Warned Bros", diff --git a/docs/scoping-and-declarations.rst b/docs/scoping-and-declarations.rst index 7165ec6e4d..838720c25b 100644 --- a/docs/scoping-and-declarations.rst +++ b/docs/scoping-and-declarations.rst @@ -8,7 +8,7 @@ Variable Declaration The first time a variable is referenced you must declare its :ref:`type `: -.. code-block:: python +.. code-block:: vyper data: int128 @@ -25,7 +25,7 @@ Declaring Public Variables Storage variables can be marked as ``public`` during declaration: -.. code-block:: python +.. code-block:: vyper data: public(int128) @@ -38,7 +38,7 @@ Declaring Immutable Variables Variables can be marked as ``immutable`` during declaration: -.. code-block:: python +.. code-block:: vyper DATA: immutable(uint256) @@ -55,7 +55,7 @@ Tuple Assignment You cannot directly declare tuple types. However, in certain cases you can use literal tuples during assignment. For example, when a function returns multiple values: -.. code-block:: python +.. code-block:: vyper @internal def foo() -> (int128, int128): @@ -84,13 +84,13 @@ This can be performed when compiling via ``vyper`` by including the ``--storage For example, consider upgrading the following contract: -.. code-block:: python +.. code-block:: vyper # old_contract.vy owner: public(address) balanceOf: public(HashMap[address, uint256]) -.. code-block:: python +.. code-block:: vyper # new_contract.vy owner: public(address) @@ -101,7 +101,7 @@ This would cause an issue when upgrading, as the ``balanceOf`` mapping would be This issue can be avoided by allocating ``balanceOf`` to ``slot1`` using the storage layout overrides. The contract can be compiled with ``vyper new_contract.vy --storage-layout-file new_contract_storage.json`` where ``new_contract_storage.json`` contains the following: -.. code-block:: javascript +.. code-block:: json { "owner": {"type": "address", "slot": 0}, @@ -130,7 +130,7 @@ Accessing Module Scope from Functions Values that are declared in the module scope of a contract, such as storage variables and functions, are accessed via the ``self`` object: -.. code-block:: python +.. code-block:: vyper a: int128 @@ -148,7 +148,7 @@ Name Shadowing It is not permitted for a memory or calldata variable to shadow the name of an immutable or constant value. The following examples will not compile: -.. code-block:: python +.. code-block:: vyper a: constant(bool) = True @@ -157,7 +157,7 @@ It is not permitted for a memory or calldata variable to shadow the name of an i # memory variable cannot have the same name as a constant or immutable variable a: bool = False return a -.. code-block:: python +.. code-block:: vyper a: immutable(bool) @@ -174,7 +174,7 @@ Function Scope Variables that are declared within a function, or given as function input arguments, are visible within the body of that function. For example, the following contract is valid because each declaration of ``a`` only exists within one function's body. -.. code-block:: python +.. code-block:: vyper @external def foo(a: int128): @@ -190,14 +190,14 @@ Variables that are declared within a function, or given as function input argume The following examples will not compile: -.. code-block:: python +.. code-block:: vyper @external def foo(a: int128): # `a` has already been declared as an input argument a: int128 = 21 -.. code-block:: python +.. code-block:: vyper @external def foo(a: int128): @@ -215,7 +215,7 @@ Block Scopes Logical blocks created by ``for`` and ``if`` statements have their own scope. For example, the following contract is valid because ``x`` only exists within the block scopes for each branch of the ``if`` statement: -.. code-block:: python +.. code-block:: vyper @external def foo(a: bool) -> int128: @@ -226,7 +226,7 @@ Logical blocks created by ``for`` and ``if`` statements have their own scope. Fo In a ``for`` statement, the target variable exists within the scope of the loop. For example, the following contract is valid because ``i`` is no longer available upon exiting the loop: -.. code-block:: python +.. code-block:: vyper @external def foo(a: bool) -> int128: @@ -236,7 +236,7 @@ In a ``for`` statement, the target variable exists within the scope of the loop. The following contract fails to compile because ``a`` has not been declared outside of the loop. -.. code-block:: python +.. code-block:: vyper @external def foo(a: bool) -> int128: diff --git a/docs/statements.rst b/docs/statements.rst index 02854adffd..34f15828a1 100644 --- a/docs/statements.rst +++ b/docs/statements.rst @@ -13,7 +13,7 @@ break The ``break`` statement terminates the nearest enclosing ``for`` loop. -.. code-block:: python +.. code-block:: vyper for i in [1, 2, 3, 4, 5]: if i == a: @@ -26,7 +26,7 @@ continue The ``continue`` statement begins the next cycle of the nearest enclosing ``for`` loop. -.. code-block:: python +.. code-block:: vyper for i in [1, 2, 3, 4, 5]: if i != a: @@ -40,7 +40,7 @@ pass ``pass`` is a null operation — when it is executed, nothing happens. It is useful as a placeholder when a statement is required syntactically, but no code needs to be executed: -.. code-block:: python +.. code-block:: vyper # this function does nothing (yet!) @@ -53,7 +53,7 @@ return ``return`` leaves the current function call with the expression list (or None) as a return value. -.. code-block:: python +.. code-block:: vyper return RETURN_VALUE @@ -69,7 +69,7 @@ log The ``log`` statement is used to log an event: -.. code-block:: python +.. code-block:: vyper log MyEvent(...) @@ -89,7 +89,7 @@ raise The ``raise`` statement triggers an exception and reverts the current call. -.. code-block:: python +.. code-block:: vyper raise "something went wrong" @@ -100,7 +100,7 @@ assert The ``assert`` statement makes an assertion about a given condition. If the condition evaluates falsely, the transaction is reverted. -.. code-block:: python +.. code-block:: vyper assert x > 5, "value too low" @@ -108,7 +108,7 @@ The error string is not required. If it is provided, it is limited to 1024 bytes This method's behavior is equivalent to: -.. code-block:: python +.. code-block:: vyper if not cond: raise "reason" diff --git a/docs/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst index 3861bf4380..561f3000dd 100644 --- a/docs/structure-of-a-contract.rst +++ b/docs/structure-of-a-contract.rst @@ -10,7 +10,7 @@ This section provides a quick overview of the types of data present within a con .. _structure-versions: Pragmas -============== +======= Vyper supports several source code directives to control compiler modes and help with build reproducibility. @@ -21,7 +21,7 @@ The version pragma ensures that a contract is only compiled by the intended comp As of 0.3.10, the recommended way to specify the version pragma is as follows: -.. code-block:: python +.. code-block:: vyper #pragma version ^0.3.0 @@ -31,7 +31,7 @@ As of 0.3.10, the recommended way to specify the version pragma is as follows: The following declaration is equivalent, and, prior to 0.3.10, was the only supported method to specify the compiler version: -.. code-block:: python +.. code-block:: vyper # @version ^0.3.0 @@ -43,7 +43,7 @@ Optimization Mode The optimization mode can be one of ``"none"``, ``"codesize"``, or ``"gas"`` (default). For example, adding the following line to a contract will cause it to try to optimize for codesize: -.. code-block:: python +.. code-block:: vyper #pragma optimize codesize @@ -62,13 +62,13 @@ State Variables State variables are values which are permanently stored in contract storage. They are declared outside of the body of any functions, and initially contain the :ref:`default value` for their type. -.. code-block:: python +.. code-block:: vyper storedData: int128 State variables are accessed via the :ref:`self` object. -.. code-block:: python +.. code-block:: vyper self.storedData = 123 @@ -81,7 +81,7 @@ Functions Functions are executable units of code within a contract. -.. code-block:: python +.. code-block:: vyper @external def bid(): @@ -96,7 +96,7 @@ Events Events provide an interface for the EVM's logging facilities. Events may be logged with specially indexed data structures that allow clients, including light clients, to efficiently search for them. -.. code-block:: python +.. code-block:: vyper event Payment: amount: int128 @@ -119,19 +119,19 @@ An interface is a set of function definitions used to enable calls between smart Interfaces can be added to contracts either through inline definition, or by importing them from a separate file. -.. code-block:: python +.. code-block:: vyper interface FooBar: def calculate() -> uint256: view def test1(): nonpayable -.. code-block:: python +.. code-block:: vyper from foo import FooBar Once defined, an interface can then be used to make external calls to a given address: -.. code-block:: python +.. code-block:: vyper @external def test(some_address: address): @@ -144,7 +144,7 @@ Structs A struct is a custom defined type that allows you to group several variables together: -.. code-block:: python +.. code-block:: vyper struct MyStruct: value1: int128 diff --git a/docs/testing-contracts-brownie.rst b/docs/testing-contracts-brownie.rst index bff871d38a..46d8df6ea6 100644 --- a/docs/testing-contracts-brownie.rst +++ b/docs/testing-contracts-brownie.rst @@ -12,7 +12,7 @@ Getting Started In order to use Brownie for testing you must first `initialize a new project `_. Create a new directory for the project, and from within that directory type: -:: +.. code:: shell $ brownie init @@ -24,12 +24,14 @@ Writing a Basic Test Assume the following simple contract ``Storage.vy``. It has a single integer variable and a function to set that value. .. literalinclude:: ../examples/storage/storage.vy - :language: python + :caption: storage.vy + :language: vyper :linenos: We create a test file ``tests/test_storage.py`` where we write our tests in pytest style. .. code-block:: python + :caption: test_storage.py :linenos: import pytest @@ -70,9 +72,10 @@ In this example we are using two fixtures which are provided by Brownie: Testing Events ============== -For the remaining examples, we expand our simple storage contract to include an event and two conditions for a failed transaction: ``AdvancedStorage.vy`` +For the remaining examples, we expand our simple storage contract to include an event and two conditions for a failed transaction: ``advanced_storage.vy`` .. literalinclude:: ../examples/storage/advanced_storage.vy + :caption: advanced_storage.vy :linenos: :language: python diff --git a/docs/testing-contracts-ethtester.rst b/docs/testing-contracts-ethtester.rst index 27e67831de..92522a1eca 100644 --- a/docs/testing-contracts-ethtester.rst +++ b/docs/testing-contracts-ethtester.rst @@ -17,6 +17,7 @@ Prior to testing, the Vyper specific contract conversion and the blockchain rela Since the testing is done in the pytest framework, you can make use of `pytest.ini, tox.ini and setup.cfg `_ and you can use most IDEs' pytest plugins. .. literalinclude:: ../tests/conftest.py + :caption: conftest.py :language: python :linenos: @@ -30,12 +31,14 @@ Writing a Basic Test Assume the following simple contract ``storage.vy``. It has a single integer variable and a function to set that value. .. literalinclude:: ../examples/storage/storage.vy + :caption: storage.vy :linenos: - :language: python + :language: vyper We create a test file ``test_storage.py`` where we write our tests in pytest style. .. literalinclude:: ../tests/functional/examples/storage/test_storage.py + :caption: test_storage.py :linenos: :language: python @@ -50,18 +53,21 @@ Events and Failed Transactions To test events and failed transactions we expand our simple storage contract to include an event and two conditions for a failed transaction: ``advanced_storage.vy`` .. literalinclude:: ../examples/storage/advanced_storage.vy + :caption: advanced_storage.vy :linenos: - :language: python + :language: vyper Next, we take a look at the two fixtures that will allow us to read the event logs and to check for failed transactions. .. literalinclude:: ../tests/conftest.py + :caption: conftest.py :language: python :pyobject: tx_failed The fixture to assert failed transactions defaults to check for a ``TransactionFailed`` exception, but can be used to check for different exceptions too, as shown below. Also note that the chain gets reverted to the state before the failed transaction. .. literalinclude:: ../tests/conftest.py + :caption: conftest.py :language: python :pyobject: get_logs @@ -70,5 +76,6 @@ This fixture will return a tuple with all the logs for a certain event and trans Finally, we create a new file ``test_advanced_storage.py`` where we use the new fixtures to test failed transactions and events. .. literalinclude:: ../tests/functional/examples/storage/test_advanced_storage.py + :caption: test_advanced_storage.py :linenos: :language: python diff --git a/docs/types.rst b/docs/types.rst index 0f5bfe7b04..38779c2a4b 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -358,7 +358,7 @@ On the ABI level the Fixed-size bytes array is annotated as ``bytes``. Bytes literals may be given as bytes strings. -.. code-block:: python +.. code-block:: vyper bytes_string: Bytes[100] = b"\x01" @@ -372,7 +372,7 @@ Strings Fixed-size strings can hold strings with equal or fewer characters than the maximum length of the string. On the ABI level the Fixed-size bytes array is annotated as ``string``. -.. code-block:: python +.. code-block:: vyper example_str: String[100] = "Test String" @@ -384,7 +384,7 @@ Flags Flags are custom defined types. A flag must have at least one member, and can hold up to a maximum of 256 members. The members are represented by ``uint256`` values in the form of 2\ :sup:`n` where ``n`` is the index of the member in the range ``0 <= n <= 255``. -.. code-block:: python +.. code-block:: vyper # Defining a flag with two members flag Roles: @@ -430,7 +430,7 @@ Flag members can be combined using the above bitwise operators. While flag membe The ``in`` and ``not in`` operators can be used in conjunction with flag member combinations to check for membership. -.. code-block:: python +.. code-block:: vyper flag Roles: MANAGER @@ -491,7 +491,7 @@ Fixed-size lists hold a finite number of elements which belong to a specified ty Lists can be declared with ``_name: _ValueType[_Integer]``, except ``Bytes[N]``, ``String[N]`` and flags. -.. code-block:: python +.. code-block:: vyper # Defining a list exampleList: int128[3] @@ -507,7 +507,7 @@ Multidimensional lists are also possible. The notation for the declaration is re A two dimensional list can be declared with ``_name: _ValueType[inner_size][outer_size]``. Elements can be accessed with ``_name[outer_index][inner_index]``. -.. code-block:: python +.. code-block:: vyper # Defining a list with 2 rows and 5 columns and set all values to 0 exampleList2D: int128[5][2] = empty(int128[5][2]) @@ -531,7 +531,7 @@ Dynamic Arrays Dynamic arrays represent bounded arrays whose length can be modified at runtime, up to a bound specified in the type. They can be declared with ``_name: DynArray[_Type, _Integer]``, where ``_Type`` can be of value type or reference type (except mappings). -.. code-block:: python +.. code-block:: vyper # Defining a list exampleList: DynArray[int128, 3] @@ -558,7 +558,7 @@ Dynamic arrays represent bounded arrays whose length can be modified at runtime, .. note:: To keep code easy to reason about, modifying an array while using it as an iterator is disallowed by the language. For instance, the following usage is not allowed: - .. code-block:: python + .. code-block:: vyper for item in self.my_array: self.my_array[0] = item @@ -580,7 +580,7 @@ Struct types can be used inside mappings and arrays. Structs can contain arrays Struct members can be accessed via ``struct.argname``. -.. code-block:: python +.. code-block:: vyper # Defining a struct struct MyStruct: @@ -610,7 +610,7 @@ Mapping types are declared as ``HashMap[_KeyType, _ValueType]``. .. note:: Mappings are only allowed as state variables. -.. code-block:: python +.. code-block:: vyper # Defining a mapping exampleMapping: HashMap[int128, decimal] diff --git a/docs/vyper-by-example.rst b/docs/vyper-by-example.rst index b07842cd25..61b5e51c41 100644 --- a/docs/vyper-by-example.rst +++ b/docs/vyper-by-example.rst @@ -19,7 +19,7 @@ period ends, a predetermined beneficiary will receive the amount of the highest bid. .. literalinclude:: ../examples/auctions/simple_open_auction.vy - :language: python + :language: vyper :linenos: As you can see, this example only has a constructor, two methods to call, and @@ -29,7 +29,7 @@ need for a basic implementation of an auction smart contract. Let's get started! .. literalinclude:: ../examples/auctions/simple_open_auction.vy - :language: python + :language: vyper :lineno-start: 3 :lines: 3-17 @@ -54,7 +54,7 @@ within the same contract. The ``public`` function additionally creates a Now, the constructor. .. literalinclude:: ../examples/auctions/simple_open_auction.vy - :language: python + :language: vyper :lineno-start: 22 :lines: 22-27 @@ -72,7 +72,7 @@ caller as we will soon see. With initial setup out of the way, lets look at how our users can make bids. .. literalinclude:: ../examples/auctions/simple_open_auction.vy - :language: python + :language: vyper :lineno-start: 33 :lines: 33-46 @@ -95,7 +95,7 @@ We will send back the previous ``highestBid`` to the previous ``highestBidder`` our new ``highestBid`` and ``highestBidder``. .. literalinclude:: ../examples/auctions/simple_open_auction.vy - :language: python + :language: vyper :lineno-start: 60 :lines: 60-85 @@ -141,13 +141,13 @@ Solidity, this blind auction allows for an auction where there is no time pressu .. _counterpart: https://solidity.readthedocs.io/en/v0.5.0/solidity-by-example.html#id2 .. literalinclude:: ../examples/auctions/blind_auction.vy - :language: python + :language: vyper :linenos: While this blind auction is almost functionally identical to the blind auction implemented in Solidity, the differences in their implementations help illustrate the differences between Solidity and Vyper. .. literalinclude:: ../examples/auctions/blind_auction.vy - :language: python + :language: vyper :lineno-start: 28 :lines: 28-30 @@ -184,14 +184,14 @@ we want to explore one way how an escrow system can be implemented trustlessly. Let's go! .. literalinclude:: ../examples/safe_remote_purchase/safe_remote_purchase.vy - :language: python + :language: vyper :linenos: This is also a moderately short contract, however a little more complex in logic. Let's break down this contract bit by bit. .. literalinclude:: ../examples/safe_remote_purchase/safe_remote_purchase.vy - :language: python + :language: vyper :lineno-start: 16 :lines: 16-19 @@ -200,7 +200,7 @@ their respective data types. Remember that the ``public`` function allows the variables to be *readable* by an external caller, but not *writeable*. .. literalinclude:: ../examples/safe_remote_purchase/safe_remote_purchase.vy - :language: python + :language: vyper :lineno-start: 22 :lines: 22-29 @@ -215,7 +215,7 @@ in the contract variable ``self.value`` and saves the contract creator into ``True``. .. literalinclude:: ../examples/safe_remote_purchase/safe_remote_purchase.vy - :language: python + :language: vyper :lineno-start: 31 :lines: 31-36 @@ -231,7 +231,7 @@ contract will call the ``selfdestruct()`` function and refunds the seller and subsequently destroys the contract. .. literalinclude:: ../examples/safe_remote_purchase/safe_remote_purchase.vy - :language: python + :language: vyper :lineno-start: 38 :lines: 38-45 @@ -244,7 +244,7 @@ contract has a balance equal to 4 times the item value and the seller must send the item to the buyer. .. literalinclude:: ../examples/safe_remote_purchase/safe_remote_purchase.vy - :language: python + :language: vyper :lineno-start: 47 :lines: 47-61 @@ -276,14 +276,14 @@ Participants will be refunded their respective contributions if the total funding does not reach its target goal. .. literalinclude:: ../examples/crowdfund.vy - :language: python + :language: vyper :linenos: Most of this code should be relatively straightforward after going through our previous examples. Let's dive right in. .. literalinclude:: ../examples/crowdfund.vy - :language: python + :language: vyper :lineno-start: 3 :lines: 3-13 @@ -304,7 +304,7 @@ once the crowdfunding period is over—as determined by the ``deadline`` and of all participants. .. literalinclude:: ../examples/crowdfund.vy - :language: python + :language: vyper :lineno-start: 9 :lines: 9-15 @@ -317,7 +317,7 @@ a definitive end time for the crowdfunding period. Now lets take a look at how a person can participate in the crowdfund. .. literalinclude:: ../examples/crowdfund.vy - :language: python + :language: vyper :lineno-start: 17 :lines: 17-23 @@ -331,7 +331,7 @@ mapping, ``self.nextFunderIndex`` increments appropriately to properly index each participant. .. literalinclude:: ../examples/crowdfund.vy - :language: python + :language: vyper :lineno-start: 25 :lines: 25-31 @@ -352,7 +352,7 @@ crowdfunding campaign isn't successful? We're going to need a way to refund all the participants. .. literalinclude:: ../examples/crowdfund.vy - :language: python + :language: vyper :lineno-start: 33 :lines: 33-42 @@ -374,14 +374,14 @@ determined upon calling the ``winningProposals()`` method, which iterates throug all the proposals and returns the one with the greatest number of votes. .. literalinclude:: ../examples/voting/ballot.vy - :language: python + :language: vyper :linenos: As we can see, this is the contract of moderate length which we will dissect section by section. Let’s begin! .. literalinclude:: ../examples/voting/ballot.vy - :language: python + :language: vyper :lineno-start: 3 :lines: 3-25 @@ -402,7 +402,7 @@ their respective datatypes. Let’s move onto the constructor. .. literalinclude:: ../examples/voting/ballot.vy - :language: python + :language: vyper :lineno-start: 53 :lines: 53-62 @@ -421,7 +421,7 @@ their respective index in the original array as its key. Now that the initial setup is done, lets take a look at the functionality. .. literalinclude:: ../examples/voting/ballot.vy - :language: python + :language: vyper :lineno-start: 66 :lines: 66-75 @@ -437,7 +437,7 @@ voting power, we will set their ``weight`` to ``1`` and we will keep track of th total number of voters by incrementing ``voterCount``. .. literalinclude:: ../examples/voting/ballot.vy - :language: python + :language: vyper :lineno-start: 120 :lines: 120-135 @@ -452,7 +452,7 @@ the delegate had already voted or increase the delegate’s vote ``weight`` if the delegate has not yet voted. .. literalinclude:: ../examples/voting/ballot.vy - :language: python + :language: vyper :lineno-start: 139 :lines: 139-151 @@ -472,7 +472,7 @@ costs gas. By having the ``@view`` decorator, we let the EVM know that this is a read-only function and we benefit by saving gas fees. .. literalinclude:: ../examples/voting/ballot.vy - :language: python + :language: vyper :lineno-start: 153 :lines: 153-170 @@ -484,7 +484,7 @@ respectively by looping through all the proposals. ``winningProposal()`` is an external function allowing access to ``_winningProposal()``. .. literalinclude:: ../examples/voting/ballot.vy - :language: python + :language: vyper :lineno-start: 175 :lines: 175-178 @@ -515,7 +515,7 @@ contract, holds all shares of the company at first but can sell them all. Let's get started. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :linenos: .. note:: Throughout this contract, we use a pattern where ``@external`` functions return data from ``@internal`` functions that have the same name prepended with an underscore. This is because Vyper does not allow calls between external functions within the same contract. The internal function handles the logic, while the external function acts as a getter to allow viewing. @@ -526,7 +526,7 @@ that the contract logs. We then declare our global variables, followed by function definitions. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 3 :lines: 3-27 @@ -537,7 +537,7 @@ represents the wei value of a share and ``holdings`` is a mapping that maps an address to the number of shares the address owns. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 29 :lines: 29-40 @@ -548,7 +548,7 @@ company's address is initialized to hold all shares of the company in the ``holdings`` mapping. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 42 :lines: 42-46 @@ -567,7 +567,7 @@ Now, lets take a look at a method that lets a person buy stock from the company's holding. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 51 :lines: 51-64 @@ -579,7 +579,7 @@ and transferred to the sender's in the ``holdings`` mapping. Now that people can buy shares, how do we check someone's holdings? .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 66 :lines: 66-71 @@ -588,7 +588,7 @@ and returns its corresponding stock holdings by keying into ``self.holdings``. Again, an external function ``getHolding()`` is included to allow access. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 72 :lines: 72-76 @@ -596,7 +596,7 @@ To check the ether balance of the company, we can simply call the getter method ``cash()``. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 78 :lines: 78-95 @@ -609,7 +609,7 @@ ether to complete the sale. If all conditions are met, the holdings are deducted from the seller and given to the company. The ethers are then sent to the seller. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 97 :lines: 97-110 @@ -620,7 +620,7 @@ than ``0`` and ``asserts`` whether the sender has enough stocks to send. If both conditions are satisfied, the transfer is made. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 112 :lines: 112-124 @@ -632,7 +632,7 @@ enough funds to pay the amount. If both conditions satisfy, the contract sends its ether to an address. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 126 :lines: 126-130 @@ -641,7 +641,7 @@ shares the company has sold and the price of each share. Internally, we get this value by calling the ``_debt()`` method. Externally it is accessed via ``debt()``. .. literalinclude:: ../examples/stock/company.vy - :language: python + :language: vyper :lineno-start: 132 :lines: 132-138 diff --git a/docs/vyper-logo-transparent.svg b/docs/vyper-logo-transparent.svg deleted file mode 100644 index 18bf3c25e2..0000000000 --- a/docs/vyper-logo-transparent.svg +++ /dev/null @@ -1,11 +0,0 @@ - diff --git a/examples/tokens/ERC20.vy b/examples/tokens/ERC20.vy index 0e94b32b9d..a9d41cbf69 100644 --- a/examples/tokens/ERC20.vy +++ b/examples/tokens/ERC20.vy @@ -31,7 +31,7 @@ decimals: public(uint8) # NOTE: By declaring `balanceOf` as public, vyper automatically generates a 'balanceOf()' getter # method to allow access to account balances. # The _KeyType will become a required parameter for the getter and it will return _ValueType. -# See: https://vyper.readthedocs.io/en/v0.1.0-beta.8/types.html?highlight=getter#mappings +# See: https://docs.vyperlang.org/en/v0.1.0-beta.8/types.html?highlight=getter#mappings balanceOf: public(HashMap[address, uint256]) # By declaring `allowance` as public, vyper automatically generates the `allowance()` getter allowance: public(HashMap[address, HashMap[address, uint256]]) diff --git a/requirements-docs.txt b/requirements-docs.txt index 5906384fc7..5c19ca7cfd 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,3 +1,3 @@ +shibuya==2024.1.17 sphinx==7.2.6 -recommonmark==0.7.1 -sphinx_rtd_theme==2.0.0 +sphinx-copybutton==0.5.2 diff --git a/tox.ini b/tox.ini index f9d4c3b60b..b42a13a0ab 100644 --- a/tox.ini +++ b/tox.ini @@ -19,9 +19,9 @@ whitelist_externals = make [testenv:docs] basepython=python3 deps = + shibuya sphinx - sphinx_rtd_theme - recommonmark + sphinx-copybutton commands = sphinx-build {posargs:-E} -b html docs dist/docs -n -q --color