Merge pull request #11662 from ethereum/docs-fix-highlighting-and-upgrade-pygments

[Docs] Fix highlighting and always use latest packages

docs/abi-spec.rst

@@ -237,6 +237,7 @@ Examples
 Given the contract:
 
 .. code-block:: solidity
+    :force:
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.4.16 <0.9.0;
@@ -657,7 +658,7 @@ As an example, the code
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >0.7.4 <0.9.0;
+    pragma solidity >=0.7.5 <0.9.0;
     pragma abicoder v2;
 
     contract Test {

docs/cheatsheet.rst

@@ -158,7 +158,8 @@ Global Variables
 Function Visibility Specifiers
 ==============================
 
-::
+.. code-block:: solidity
+    :force:
 
     function myFunction() <visibility specifier> returns (bool) {
         return true;

docs/common-patterns.rst

@@ -130,6 +130,7 @@ The use of **function modifiers** makes these
 restrictions highly readable.
 
 .. code-block:: solidity
+    :force:
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity ^0.8.4;
@@ -293,6 +294,7 @@ function finishes.
     will run even if the function explicitly returns.
 
 .. code-block:: solidity
+    :force:
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity ^0.8.4;

docs/contracts/events.rst

@@ -97,7 +97,7 @@ four indexed arguments rather than three.
 
 The use in the JavaScript API is as follows:
 
-::
+.. code-block:: javascript
 
     var abi = /* abi as generated by the compiler */;
     var ClientReceipt = web3.eth.contract(abi);

docs/contracts/function-modifiers.rst

@@ -18,7 +18,7 @@ if they are marked ``virtual``. For details, please see
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >0.7.0 <0.9.0;
+    pragma solidity >=0.7.1 <0.9.0;
 
     contract owned {
         constructor() { owner = payable(msg.sender); }

docs/contracts/functions.rst

@@ -15,7 +15,7 @@ that call them, similar to internal library functions.
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >0.7.0 <0.9.0;
+    pragma solidity >=0.7.1 <0.9.0;
 
     function sum(uint[] memory _arr) pure returns (uint s) {
         for (uint i = 0; i < _arr.length; i++)

docs/contracts/libraries.rst

@@ -130,6 +130,7 @@ internal functions in libraries in order to implement
 custom types without the overhead of external function calls:
 
 .. code-block:: solidity
+    :force:
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity ^0.8.0;

docs/control-structures.rst

@@ -660,6 +660,7 @@ The following example shows how you can use ``require`` to check conditions on i
 and ``assert`` for internal error checking.
 
 .. code-block:: solidity
+    :force:
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.5.0 <0.9.0;
@@ -786,7 +787,7 @@ A failure in an external call can be caught using a try/catch statement, as foll
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >0.8.0;
+    pragma solidity >=0.8.1;
 
     interface DataFeed { function getData(address token) external returns (uint value); }
 

docs/examples/blind-auction.rst

@@ -192,6 +192,7 @@ invalid bids.
 
 
 .. code-block:: solidity
+    :force:
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity ^0.8.4;

docs/internals/optimizer.rst

@@ -696,7 +696,7 @@ operation where ``unused = 0``, ``undecided = 1`` and ``used = 2``.
 
 The proper way would be to compute
 
-::
+.. code-block:: none
 
     max(s, f(s), f(f(s)), f(f(f(s))), ...)
 
@@ -705,7 +705,7 @@ iterating it has to reach a cycle after at most three iterations,
 and thus ``f(f(f(s)))`` has to equal one of ``s``, ``f(s)``, or ``f(f(s))``
 and thus
 
-::
+.. code-block:: none
 
     max(s, f(s), f(f(s))) = max(s, f(s), f(f(s)), f(f(f(s))), ...).
 
@@ -1263,7 +1263,7 @@ Reverses the transformation of ForLoopConditionIntoBody.
 
 For any movable ``c``, it turns
 
-::
+.. code-block:: none
 
     for { ... } 1 { ... } {
     if iszero(c) { break }
@@ -1272,7 +1272,7 @@ For any movable ``c``, it turns
 
 into
 
-::
+.. code-block:: none
 
     for { ... } c { ... } {
     ...
@@ -1280,7 +1280,7 @@ into
 
 and it turns
 
-::
+.. code-block:: none
 
     for { ... } 1 { ... } {
     if c { break }
@@ -1289,7 +1289,7 @@ and it turns
 
 into
 
-::
+.. code-block:: none
 
     for { ... } iszero(c) { ... } {
     ...

docs/introduction-to-smart-contracts.rst

@@ -140,7 +140,9 @@ of a keypair belonging to :ref:`external accounts<accounts>`.
 The keyword ``public`` automatically generates a function that allows you to access the current value of the state
 variable from outside of the contract. Without this keyword, other contracts have no way to access the variable.
 The code of the function generated by the compiler is equivalent
-to the following (ignore ``external`` and ``view`` for now)::
+to the following (ignore ``external`` and ``view`` for now):
+
+.. code-block:: solidity
 
     function minter() external view returns (address) { return minter; }
 
@@ -162,7 +164,9 @@ even better, keep a list, or use a more suitable data type.
 
 The :ref:`getter function<getter-functions>` created by the ``public`` keyword
 is more complex in the case of a mapping. It looks like the
-following::
+following:
+
+.. code-block:: solidity
 
     function balances(address _account) external view returns (uint) {
         return balances[_account];

docs/ir/ir-breaking-changes.rst

@@ -17,7 +17,7 @@ hiding new and different behavior in existing code.
   .. code-block:: solidity
 
       // SPDX-License-Identifier: GPL-3.0
-      pragma solidity >0.7.0;
+      pragma solidity >=0.7.1;
 
       contract C {
           struct S {
@@ -80,7 +80,7 @@ This causes differences in some contracts, for example:
   .. code-block:: solidity
 
       // SPDX-License-Identifier: GPL-3.0
-      pragma solidity >0.7.0;
+      pragma solidity >=0.7.1;
 
       contract A {
           uint x;
@@ -104,7 +104,7 @@ This causes differences in some contracts, for example:
   .. code-block:: solidity
 
       // SPDX-License-Identifier: GPL-3.0
-      pragma solidity >0.8.0;
+      pragma solidity >=0.8.1;
 
       contract C {
           bytes x;
@@ -135,7 +135,7 @@ This causes differences in some contracts, for example:
   .. code-block:: solidity
 
       // SPDX-License-Identifier: GPL-3.0
-      pragma solidity >0.8.0;
+      pragma solidity >=0.8.1;
       contract C {
           function preincr_u8(uint8 _a) public pure returns (uint8) {
               return ++_a + _a;
@@ -155,7 +155,7 @@ This causes differences in some contracts, for example:
   .. code-block:: solidity
 
       // SPDX-License-Identifier: GPL-3.0
-      pragma solidity >0.8.0;
+      pragma solidity >=0.8.1;
       contract C {
           function add(uint8 _a, uint8 _b) public pure returns (uint8) {
               return _a + _b;
@@ -174,10 +174,10 @@ This causes differences in some contracts, for example:
   and left-to-right by the new code generator.
   For example:
 
-  ::
+  .. code-block:: solidity
 
       // SPDX-License-Identifier: GPL-3.0
-      pragma solidity >0.8.0;
+      pragma solidity >=0.8.1;
       contract C {
           function f() public pure returns (uint256 aMod, uint256 mMod) {
               uint256 x = 3;
@@ -250,9 +250,10 @@ The new code generator performs cleanup after any operation that can result in d
 For example:
 
 .. code-block:: solidity
+    :force:
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >0.8.0;
+    pragma solidity >=0.8.1;
     contract C {
         function f(uint8 _a) public pure returns (uint _r1, uint _r2)
         {

docs/layout-of-source-files.rst

@@ -180,7 +180,7 @@ a `default export <https://developer.mozilla.org/en-US/docs/web/javascript/refer
 
 At a global level, you can use import statements of the following form:
 
-::
+.. code-block:: solidity
 
     import "filename";
 
@@ -195,7 +195,7 @@ symbols explicitly.
 The following example creates a new global symbol ``symbolName`` whose members are all
 the global symbols from ``"filename"``:
 
-::
+.. code-block:: solidity
 
     import * as symbolName from "filename";
 
@@ -203,7 +203,7 @@ which results in all global symbols being available in the format ``symbolName.s
 
 A variant of this syntax that is not part of ES6, but possibly useful is:
 
-::
+.. code-block:: solidity
 
   import "filename" as symbolName;
 
@@ -213,7 +213,7 @@ If there is a naming collision, you can rename symbols while importing. For exam
 the code below creates new global symbols ``alias`` and ``symbol2`` which reference
 ``symbol1`` and ``symbol2`` from inside ``"filename"``, respectively.
 
-::
+.. code-block:: solidity
 
     import {symbol1 as alias, symbol2} from "filename";
 
@@ -253,7 +253,7 @@ Comments
 
 Single-line comments (``//``) and multi-line comments (``/*...*/``) are possible.
 
-::
+.. code-block:: solidity
 
     // This is a single-line comment.
 

docs/metadata.rst

@@ -31,24 +31,24 @@ reduce whitespace to a minimum and sort the keys of all objects to arrive at a
 unique formatting. Comments are not permitted and used here only for
 explanatory purposes.
 
-.. code-block:: none
+.. code-block:: javascript
 
     {
       // Required: The version of the metadata format
-      version: "1",
+      "version": "1",
       // Required: Source code language, basically selects a "sub-version"
       // of the specification
-      language: "Solidity",
+      "language": "Solidity",
       // Required: Details about the compiler, contents are specific
       // to the language.
-      compiler: {
+      "compiler": {
         // Required for Solidity: Version of the compiler
-        version: "0.4.6+commit.2dabbdf0.Emscripten.clang",
+        "version": "0.4.6+commit.2dabbdf0.Emscripten.clang",
         // Optional: Hash of the compiler binary which produced this output
-        keccak256: "0x123..."
+        "keccak256": "0x123..."
       },
       // Required: Compilation source files/source units, keys are file names
-      sources:
+      "sources":
       {
         "myFile.sol": {
           // Required: keccak256 hash of the source file
@@ -68,59 +68,59 @@ explanatory purposes.
         }
       },
       // Required: Compiler settings
-      settings:
+      "settings":
       {
         // Required for Solidity: Sorted list of remappings
-        remappings: [ ":g=/dir" ],
+        "remappings": [ ":g=/dir" ],
         // Optional: Optimizer settings. The fields "enabled" and "runs" are deprecated
         // and are only given for backwards-compatibility.
-        optimizer: {
+        "optimizer": {
-          enabled: true,
+          "enabled": true,
-          runs: 500,
+          "runs": 500,
-          details: {
+          "details": {
             // peephole defaults to "true"
-            peephole: true,
+            "peephole": true,
             // inliner defaults to "true"
-            inliner: true,
+            "inliner": true,
             // jumpdestRemover defaults to "true"
-            jumpdestRemover: true,
+            "jumpdestRemover": true,
-            orderLiterals: false,
+            "orderLiterals": false,
-            deduplicate: false,
+            "deduplicate": false,
-            cse: false,
+            "cse": false,
-            constantOptimizer: false,
+            "constantOptimizer": false,
-            yul: true,
+            "yul": true,
             // Optional: Only present if "yul" is "true"
-            yulDetails: {
+            "yulDetails": {
-              stackAllocation: false,
+              "stackAllocation": false,
-              optimizerSteps: "dhfoDgvulfnTUtnIf..."
+              "optimizerSteps": "dhfoDgvulfnTUtnIf..."
             }
           }
         },
-        metadata: {
+        "metadata": {
           // Reflects the setting used in the input json, defaults to false
-          useLiteralContent: true,
+          "useLiteralContent": true,
           // Reflects the setting used in the input json, defaults to "ipfs"
-          bytecodeHash: "ipfs"
+          "bytecodeHash": "ipfs"
-        }
+        },
         // Required for Solidity: File and name of the contract or library this
         // metadata is created for.
-        compilationTarget: {
+        "compilationTarget": {
           "myFile.sol": "MyContract"
         },
         // Required for Solidity: Addresses for libraries used
-        libraries: {
+        "libraries": {
           "MyLib": "0x123123..."
         }
       },
       // Required: Generated information about the contract.
-      output:
+      "output":
       {
         // Required: ABI definition of the contract
-        abi: [ ... ],
+        "abi": [/* ... */],
         // Required: NatSpec user documentation of the contract
-        userdoc: [ ... ],
+        "userdoc": [/* ... */],
         // Required: NatSpec developer documentation of the contract
-        devdoc: [ ... ],
+        "devdoc": [/* ... */]
       }
     }
 
@@ -147,7 +147,9 @@ the mapping ``{"ipfs": <IPFS hash>, "solc": <compiler version>}`` is stored
 contain more keys (see below) and the beginning of that
 encoding is not easy to find, its length is added in a two-byte big-endian
 encoding. The current version of the Solidity compiler usually adds the following
-to the end of the deployed bytecode::
+to the end of the deployed bytecode
+
+.. code-block:: text
 
     0xa2
     0x64 'i' 'p' 'f' 's' 0x58 0x22 <34 bytes IPFS hash>

docs/path-resolution.rst

@@ -180,7 +180,7 @@ Direct Imports
 
 An import that does not start with ``./`` or ``../`` is a *direct import*.
 
-::
+.. code-block:: solidity
 
     import "/project/lib/util.sol";         // source unit name: /project/lib/util.sol
     import "lib/util.sol";                  // source unit name: lib/util.sol

docs/smtchecker.rst

@@ -97,7 +97,7 @@ The SMTChecker will, by default, check every reachable arithmetic operation
 in the contract for potential underflow and overflow.
 Here, it reports the following:
 
-.. code-block:: bash
+.. code-block:: text
 
     Warning: CHC: Overflow (resulting value larger than 2**256 - 1) happens here.
     Counterexample:
@@ -233,7 +233,7 @@ For example, changing the code to
 
 gives us:
 
-.. code-block:: bash
+.. code-block:: text
 
     Warning: CHC: Assertion violation happens here.
     Counterexample:
@@ -323,7 +323,7 @@ reachable, by adding the following function.
 This property is false, and while proving that the property is false,
 the SMTChecker tells us exactly *how* to reach (2, 4):
 
-.. code-block:: bash
+.. code-block:: text
 
     Warning: CHC: Assertion violation happens here.
     Counterexample:
@@ -410,7 +410,7 @@ If we "forget" to use the ``mutex`` modifier on function ``set``, the
 SMTChecker is able to synthesize the behavior of the externally called code so
 that the assertion fails:
 
-.. code-block:: bash
+.. code-block:: text
 
     Warning: CHC: Assertion violation happens here.
     Counterexample:
@@ -494,10 +494,9 @@ allowed) of <source>:<contract> pairs in the CLI:
 and via the object ``settings.modelChecker.contracts`` in the :ref:`JSON input<compiler-api>`,
 which has the following form:
 
-.. code-block:: none
+.. code-block:: json
 
-    contracts
+    "contracts": {
-    {
         "source1.sol": ["contract1"],
         "source2.sol": ["contract2", "contract3"]
     }

docs/structure-of-a-contract.rst

@@ -50,7 +50,7 @@ contracts.
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >0.7.0 <0.9.0;
+    pragma solidity >=0.7.1 <0.9.0;
 
     contract SimpleAuction {
         function bid() public payable { // Function

docs/style-guide.rst

@@ -410,7 +410,9 @@ No:
 
     spam( ham[ 1 ], Coin( { name: "ham" } ) );
 
-Exception::
+Exception:
+
+.. code-block:: solidity
 
     function singleLine() public { spam(); }
 
@@ -996,6 +998,7 @@ No:
 Yes:
 
 .. code-block:: solidity
+    :force:
 
     x = 3;
     x = 100 / 10;
@@ -1005,6 +1008,7 @@ Yes:
 No:
 
 .. code-block:: solidity
+    :force:
 
     x=3;
     x = 100/10;

docs/types/mapping-types.rst

@@ -122,6 +122,7 @@ top of them and iterate over that. For example, the code below implements an
 the ``sum`` function iterates over to sum all the values.
 
 .. code-block:: solidity
+    :force:
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.6.8 <0.9.0;

docs/types/reference-types.rst

@@ -496,7 +496,7 @@ Array slices are useful to ABI-decode secondary data passed in function paramete
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >0.8.4 <0.9.0;
+    pragma solidity >=0.8.5 <0.9.0;
     contract Proxy {
         /// @dev Address of the client contract managed by proxy i.e., this contract
         address client;

docs/types/value-types.rst

@@ -239,6 +239,7 @@ It is possible to query the balance of an address using the property ``balance``
 and to send Ether (in units of wei) to a payable address using the ``transfer`` function:
 
 .. code-block:: solidity
+    :force:
 
     address payable x = address(0x123);
     address myAddress = address(this);
@@ -534,7 +535,8 @@ It starts with a newline byte, followed by a double quote, a single
 quote a backslash character and then (without separator) the
 character sequence ``abcdef``.
 
-::
+.. code-block:: solidity
+    :force:
 
     "\n\"\'\\abc\
     def"
@@ -641,6 +643,7 @@ be passed via and returned from external function calls.
 Function types are notated as follows:
 
 .. code-block:: solidity
+    :force:
 
     function (<parameter types>) {internal|external} [pure|view|payable] [returns (<return types>)]
 

docs/units-and-global-variables.rst

@@ -10,6 +10,7 @@ Ether Units
 A literal number can take a suffix of ``wei``, ``gwei`` or ``ether`` to specify a subdenomination of Ether, where Ether numbers without a postfix are assumed to be Wei.
 
 .. code-block:: solidity
+    :force:
 
     assert(1 wei == 1);
     assert(1 gwei == 1e9);

docs/using-the-compiler.rst

@@ -41,7 +41,7 @@ Base Path and Import Remapping
 The commandline compiler will automatically read imported files from the filesystem, but
 it is also possible to provide :ref:`path redirects <import-remapping>` using ``prefix=path`` in the following way:
 
-::
+.. code-block:: bash
 
     solc github.com/ethereum/dapp-bin/=/usr/local/lib/dapp-bin/ file.sol
 
@@ -134,12 +134,12 @@ On the command line, you can select the EVM version as follows:
 In the :ref:`standard JSON interface <compiler-api>`, use the ``"evmVersion"``
 key in the ``"settings"`` field:
 
-.. code-block:: none
+.. code-block:: javascript
 
     {
-      "sources": { ... },
+      "sources": {/* ... */},
       "settings": {
-        "optimizer": { ... },
+        "optimizer": {/* ... */},
         "evmVersion": "<VERSION>"
       }
     }
@@ -198,7 +198,7 @@ Comments are of course not permitted and used here only for explanatory purposes
 Input Description
 -----------------
 
-.. code-block:: none
+.. code-block:: javascript
 
     {
       // Required: Source code language. Currently supported are "Solidity" and "Yul".
@@ -310,7 +310,7 @@ Input Description
           // "debug" injects strings for compiler-generated internal reverts, implemented for ABI encoders V1 and V2 for now.
           // "verboseDebug" even appends further information to user-supplied revert strings (not yet implemented)
           "revertStrings": "default"
-        }
+        },
         // Metadata settings (optional)
         "metadata": {
           // Use only literal content and not URLs (false by default)
@@ -331,7 +331,7 @@ Input Description
           "myFile.sol": {
             "MyLib": "0x123123..."
           }
-        }
+        },
         // The following can be used to select desired outputs based
         // on file and contract names.
         // If this field is omitted, then the compiler loads and does type checking,
@@ -395,7 +395,7 @@ Input Description
         "modelChecker":
         {
           // Chose which contracts should be analyzed as the deployed one.
-          contracts:
+          "contracts":
           {
             "source1.sol": ["contract1"],
             "source2.sol": ["contract2", "contract3"]
@@ -420,7 +420,7 @@ Input Description
 Output Description
 ------------------
 
-.. code-block:: none
+.. code-block:: javascript
 
     {
       // Optional: not present if no errors/warnings were encountered
@@ -431,7 +431,7 @@ Output Description
             "file": "sourceFile.sol",
             "start": 0,
             "end": 100
-          ],
+          },
           // Optional: Further locations (e.g. places of conflicting declarations)
           "secondarySourceLocations": [
             {
@@ -463,7 +463,7 @@ Output Description
           // Identifier of the source (used in source maps)
           "id": 1,
           // The AST object
-          "ast": {},
+          "ast": {}
         }
       },
       // This contains the contract-level outputs.
@@ -476,7 +476,7 @@ Output Description
             // See https://docs.soliditylang.org/en/develop/abi-spec.html
             "abi": [],
             // See the Metadata Output documentation (serialised JSON string)
-            "metadata": "{...}",
+            "metadata": "{/* ... */}",
             // User documentation (natspec)
             "userdoc": {},
             // Developer documentation (natspec)
@@ -484,7 +484,7 @@ Output Description
             // Intermediate representation (string)
             "ir": "",
             // See the Storage Layout documentation.
-            "storageLayout": {"storage": [...], "types": {...} },
+            "storageLayout": {"storage": [/* ... */], "types": {/* ... */} },
             // EVM-related outputs
             "evm": {
               // Assembly (string)
@@ -514,14 +514,14 @@ Output Description
                 // contains a single Yul file.
                 "generatedSources": [{
                   // Yul AST
-                  "ast": { ... }
+                  "ast": {/* ... */},
                   // Source file in its text form (may contain comments)
                   "contents":"{ function abi_decode(start, end) -> data { data := calldataload(start) } }",
                   // Source file ID, used for source references, same "namespace" as the Solidity source files
                   "id": 2,
                   "language": "Yul",
                   "name": "#utility.yul"
-                }]
+                }],
                 // If given, this is an unlinked object.
                 "linkReferences": {
                   "libraryFile.sol": {
@@ -535,7 +535,7 @@ Output Description
                 }
               },
               "deployedBytecode": {
-                ..., // The same layout as above.
+                /* ..., */ // The same layout as above.
                 "immutableReferences": {
                   // There are two references to the immutable with AST ID 3, both 32 bytes long. One is
                   // at bytecode offset 42, the other at bytecode offset 80.
@@ -779,9 +779,9 @@ Running the Upgrade
 
 It is recommended to explicitly specify the upgrade modules by using ``--modules`` argument.
 
-.. code-block:: none
+.. code-block:: bash
 
-    $ solidity-upgrade --modules constructor-visibility,now,dotsyntax Source.sol
+    solidity-upgrade --modules constructor-visibility,now,dotsyntax Source.sol
 
 The command above applies all changes as shown below. Please review them carefully (the pragmas will
 have to be updated manually.)

scripts/docs.sh

@@ -28,6 +28,6 @@
 
 set -e
 cd docs
-pip3 install -r requirements.txt
+pip3 install -r requirements.txt --upgrade --upgrade-strategy eager
 sphinx-build -nW -b html -d _build/doctrees . _build/html
 cd ..