docs: fix formatting errors and style inconsistencies

Author: iamdefinitelyahuman

docs/contracts/functions.rst

@@ -195,7 +195,7 @@ In addition to the list of state modifying statements explained above, the follo
         }
     }
 
-Pure functions are able to use the `revert()` and `require()` functions to revert
+Pure functions are able to use the ``revert()`` and ``require()`` functions to revert
 potential state changes when an :ref:`error occurs <assert-and-require>`.
 
 Reverting a state change is not considered a "state modification", as only changes to the
@@ -235,17 +235,17 @@ A contract can have at most one ``receive`` function, declared using
 ``receive() external payable { ... }``
 (without the ``function`` keyword).
 This function cannot have arguments, cannot return anything and must have
-``external`` visibility and ``payable`` state mutability.  It is executed on a
+``external`` visibility and ``payable`` state mutability. It is executed on a
 call to the contract with empty calldata. This is the function that is executed
-on plain Ether transfers (e.g. via `.send()` or `.transfer()`).  If no such
+on plain Ether transfers (e.g. via ``.send()`` or ``.transfer()``). If no such
 function exists, but a payable :ref:`fallback function <fallback-function>`
 exists, the fallback function will be called on a plain Ether transfer. If
 neither a receive Ether nor a payable fallback function is present, the
 contract cannot receive Ether through regular transactions and throws an
 exception.
 
 In the worst case, the fallback function can only rely on 2300 gas being
-available (for example when `send` or `transfer` is used), leaving little
+available (for example when ``send`` or ``transfer`` is used), leaving little
 room to perform other operations except basic logging. The following operations
 will consume more gas than the 2300 gas stipend:
 
@@ -265,7 +265,7 @@ will consume more gas than the 2300 gas stipend:
 
 .. warning::
     A contract without a receive Ether function can receive Ether as a
-    recipient of a `coinbase transaction` (aka `miner block reward`)
+    recipient of a *coinbase transaction* (aka *miner block reward*)
     or as a destination of a ``selfdestruct``.
 
     A contract cannot react to such Ether transfers and thus also

docs/contracts/visibility-and-getters.rst

@@ -16,7 +16,7 @@ Functions have to be specified as being ``external``,
 ``public``, ``internal`` or ``private``.
 For state variables, ``external`` is not possible.
 
-``external``:
+``external``
     External functions are part of the contract interface,
     which means they can be called from other contracts and
     via transactions. An external function ``f`` cannot be called
@@ -25,18 +25,18 @@ For state variables, ``external`` is not possible.
     they receive large arrays of data, because the data
     is not copied from calldata to memory.
 
-``public``:
+``public``
     Public functions are part of the contract interface
     and can be either called internally or via
     messages. For public state variables, an automatic getter
     function (see below) is generated.
 
-``internal``:
+``internal``
     Those functions and state variables can only be
     accessed internally (i.e. from within the current contract
     or contracts deriving from it), without using ``this``.
 
-``private``:
+``private``
     Private functions and state variables are only
     visible for the contract they are defined in and not in
     derived contracts.

docs/examples/micropayment.rst

@@ -454,7 +454,7 @@ The recipient should verify each message using the following process:
 
 We'll use the `ethereumjs-util <https://github.com/ethereumjs/ethereumjs-util>`_
 library to write this verification. The final step can be done a number of ways,
-and we use JavaScript. The following code borrows the `constructMessage` function from the signing **JavaScript code** above:
+and we use JavaScript. The following code borrows the ``constructMessage`` function from the signing **JavaScript code** above:
 
 ::
 

docs/installing-solidity.rst

@@ -35,11 +35,11 @@ or if you require more compilation options.
 npm / Node.js
 =============
 
-Use `npm` for a convenient and portable way to install `solcjs`, a Solidity compiler. The
+Use ``npm`` for a convenient and portable way to install ``solcjs``, a Solidity compiler. The
 `solcjs` program has fewer features than the ways to access the compiler described
 further down this page. The
 :ref:`commandline-compiler` documentation assumes you are using
-the full-featured compiler, `solc`. The usage of `solcjs` is documented inside its own
+the full-featured compiler, ``solc``. The usage of ``solcjs`` is documented inside its own
 `repository <https://github.com/ethereum/solc-js>`_.
 
 Note: The solc-js project is derived from the C++
@@ -53,10 +53,10 @@ Please refer to the solc-js repository for instructions.
 
 .. note::
 
-    The commandline executable is named `solcjs`.
+    The commandline executable is named ``solcjs``.
 
-    The comandline options of `solcjs` are not compatible with `solc` and tools (such as `geth`)
-    expecting the behaviour of `solc` will not work with `solcjs`.
+    The comandline options of ``solcjs`` are not compatible with ``solc`` and tools (such as ``geth``)
+    expecting the behaviour of ``solc`` will not work with ``solcjs``.
 
 Docker
 ======

docs/introduction-to-smart-contracts.rst

@@ -323,7 +323,7 @@ Every account has a persistent key-value store mapping 256-bit words to 256-bit
 words called **storage**.
 
 Furthermore, every account has a **balance** in
-Ether (in "Wei" to be exact, `1 ether` is `10**18 wei`) which can be modified by sending transactions that
+Ether (in "Wei" to be exact, ``1 ether`` is ``10**18 wei``) which can be modified by sending transactions that
 include Ether.
 
 .. index:: ! transaction
@@ -520,9 +520,9 @@ idea, but it is potentially dangerous, as if someone sends Ether to removed
 contracts, the Ether is forever lost.
 
 .. warning::
-    Even if a contract is removed by "selfdestruct", it is still part of the
+    Even if a contract is removed by ``selfdestruct``, it is still part of the
     history of the blockchain and probably retained by most Ethereum nodes.
-    So using "selfdestruct" is not the same as deleting data from a hard disk.
+    So using ``selfdestruct`` is not the same as deleting data from a hard disk.
 
 .. note::
     Even if a contract's code does not contain a call to ``selfdestruct``,

docs/natspec-format.rst

@@ -73,8 +73,8 @@ Tags
 
 All tags are optional. The following table explains the purpose of each
 NatSpec tag and where it may be used. As a special case, if no tags are
-used then the Solidity compiler will interpret a `///` or `/**` comment
-in the same way as if it were tagged with `@notice`.
+used then the Solidity compiler will interpret a ``///`` or ``/**`` comment
+in the same way as if it were tagged with ``@notice``.
 
 =========== =============================================================================== =============================
 Tag                                                                                         Context

docs/style-guide.rst

@@ -24,8 +24,11 @@ solidity code.  The goal of this guide is *consistency*.  A quote from python's
 `pep8 <https://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds>`_
 captures this concept well.
 
+.. note::
+
     A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important.
-    But most importantly: know when to be inconsistent -- sometimes the style guide just doesn't apply. When in doubt, use your best judgement. Look at other examples and decide what looks best. And don't hesitate to ask!
+
+    But most importantly: **know when to be inconsistent** -- sometimes the style guide just doesn't apply. When in doubt, use your best judgement. Look at other examples and decide what looks best. And don't hesitate to ask!
 
 
 ***********
@@ -383,8 +386,7 @@ No::
 
     function spam(uint i , Coin coin) public ;
 
-More than one space around an assignment or other operator to align with
-  another:
+More than one space around an assignment or other operator to align with another:
 
 Yes::
 
@@ -996,7 +998,7 @@ Contract and Library Names
 * Contract and library names should also match their filenames.
 * If a contract file includes multiple contracts and/or libraries, then the filename should match the *core contract*. This is not recommended however if it can be avoided.
 
-As shown in the example below, if the contract name is `Congress` and the library name is `Owned`, then their associated filenames should be `Congress.sol` and `Owned.sol`.
+As shown in the example below, if the contract name is ``Congress`` and the library name is ``Owned``, then their associated filenames should be ``Congress.sol`` and ``Owned.sol``.
 
 Yes::
 
@@ -1132,8 +1134,8 @@ Solidity contracts can have a form of comments that are the basis of the
 Ethereum Natural Language Specification Format.
 
 Add comments above functions or contracts following `doxygen <http://www.doxygen.nl>`_ notation
-of one or multiple lines starting with `///` or a
-multiline comment starting with `/**` and ending with `*/`.
+of one or multiple lines starting with ``///`` or a
+multiline comment starting with ``/**`` and ending with ``*/``.
 
 For example, the contract from `a simple smart contract <simple-smart-contract>`_ with the comments
 added looks like the one below::

docs/types.rst

@@ -16,7 +16,7 @@ operators. For a quick reference of the various operators, see :ref:`order`.
 The concept of "undefined" or "null" values does not exist in Solidity, but newly
 declared variables always have a :ref:`default value<default-value>` dependent
 on its type. To handle any unexpected values, you should use the :ref:`revert function<assert-and-require>` to revert the whole transaction, or return a
-tuple with a second `bool` value denoting success.
+tuple with a second ``bool`` value denoting success.
 
 .. include:: types/value-types.rst
 
@@ -26,4 +26,4 @@ tuple with a second `bool` value denoting success.
 
 .. include:: types/operators.rst
 
-.. include:: types/conversion.rst
+.. include:: types/conversion.rst

docs/types/value-types.rst

@@ -332,7 +332,7 @@ the :ref:`address type<address>`.
     Before version 0.5.0, contracts directly derived from the address type
     and there was no distinction between ``address`` and ``address payable``.
 
-If you declare a local variable of contract type (`MyContract c`), you can call
+If you declare a local variable of contract type (``MyContract c``), you can call
 functions on that contract. Take care to assign it from somewhere that is the
 same contract type.
 

docs/units-and-global-variables.rst

@@ -140,48 +140,52 @@ Error Handling
 See the dedicated section on :ref:`assert and require<assert-and-require>` for
 more details on error handling and when to use which function.
 
-``assert(bool condition)``:
+``assert(bool condition)``
     causes an invalid opcode and thus state change reversion if the condition is not met - to be used for internal errors.
-``require(bool condition)``:
+
+``require(bool condition)``
     reverts if the condition is not met - to be used for errors in inputs or external components.
-``require(bool condition, string memory message)``:
+
+``require(bool condition, string memory message)``
     reverts if the condition is not met - to be used for errors in inputs or external components. Also provides an error message.
-``revert()``:
+
+``revert()``
     abort execution and revert state changes
-``revert(string memory reason)``:
+
+``revert(string memory reason)``
     abort execution and revert state changes, providing an explanatory string
 
 .. index:: keccak256, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography,
 
 Mathematical and Cryptographic Functions
 ----------------------------------------
 
-``addmod(uint x, uint y, uint k) returns (uint)``:
+``addmod(uint x, uint y, uint k) returns (uint)``
     compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256``. Assert that ``k != 0`` starting from version 0.5.0.
 
-``mulmod(uint x, uint y, uint k) returns (uint)``:
+``mulmod(uint x, uint y, uint k) returns (uint)``
     compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256``. Assert that ``k != 0`` starting from version 0.5.0.
 
-``keccak256(bytes memory) returns (bytes32)``:
+``keccak256(bytes memory) returns (bytes32)``
     compute the Keccak-256 hash of the input
 
 .. note::
 
     There used to be an alias for ``keccak256`` called ``sha3``, which was removed in version 0.5.0.
 
-``sha256(bytes memory) returns (bytes32)``:
+``sha256(bytes memory) returns (bytes32)``
     compute the SHA-256 hash of the input
 
-``ripemd160(bytes memory) returns (bytes20)``:
+``ripemd160(bytes memory) returns (bytes20)``
     compute RIPEMD-160 hash of the input
 
-``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``:
+``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``
     recover the address associated with the public key from elliptic curve signature or return zero on error.
     The function parameters correspond to ECDSA values of the signature:
 
-    ``r`` = first 32 bytes of signature
-    ``s`` = second 32 bytes of signature
-    ``v`` = final 1 byte of signature
+    * ``r`` = first 32 bytes of signature
+    * ``s`` = second 32 bytes of signature
+    * ``v`` = final 1 byte of signature
 
     ``ecrecover`` returns an ``address``, and not an ``address payable``. See :ref:`address payable<address>` for
     conversion, in case you need to transfer funds to the recovered address.
@@ -209,17 +213,22 @@ Mathematical and Cryptographic Functions
 Members of Address Types
 ------------------------
 
-``<address>.balance`` (``uint256``):
+``<address>.balance`` (``uint256``)
     balance of the :ref:`address` in Wei
-``<address payable>.transfer(uint256 amount)``:
+
+``<address payable>.transfer(uint256 amount)``
     send given amount of Wei to :ref:`address`, reverts on failure, forwards 2300 gas stipend, not adjustable
-``<address payable>.send(uint256 amount) returns (bool)``:
+
+``<address payable>.send(uint256 amount) returns (bool)``
     send given amount of Wei to :ref:`address`, returns ``false`` on failure, forwards 2300 gas stipend, not adjustable
-``<address>.call(bytes memory) returns (bool, bytes memory)``:
+
+``<address>.call(bytes memory) returns (bool, bytes memory)``
     issue low-level ``CALL`` with the given payload, returns success condition and return data, forwards all available gas, adjustable
-``<address>.delegatecall(bytes memory) returns (bool, bytes memory)``:
+
+``<address>.delegatecall(bytes memory) returns (bool, bytes memory)``
     issue low-level ``DELEGATECALL`` with the given payload, returns success condition and return data, forwards all available gas, adjustable
-``<address>.staticcall(bytes memory) returns (bool, bytes memory)``:
+
+``<address>.staticcall(bytes memory) returns (bool, bytes memory)``
     issue low-level ``STATICCALL`` with the given payload, returns success condition and return data, forwards all available gas, adjustable
 
 For more information, see the section on :ref:`address`.
@@ -258,10 +267,10 @@ For more information, see the section on :ref:`address`.
 Contract Related
 ----------------
 
-``this`` (current contract's type):
+``this`` (current contract's type)
     the current contract, explicitly convertible to :ref:`address`
 
-``selfdestruct(address payable recipient)``:
+``selfdestruct(address payable recipient)``
     Destroy the current contract, sending its funds to the given :ref:`address`
     and end execution.
     Note that ``selfdestruct`` has some peculiarities inherited from the EVM:
@@ -290,18 +299,18 @@ type ``X``. Currently, there is limited support for this feature, but
 it might be expanded in the future. The following properties are
 available for a contract type ``C``:
 
-``type(C).name``:
+``type(C).name``
     The name of the contract.
 
-``type(C).creationCode``:
+``type(C).creationCode``
     Memory byte array that contains the creation bytecode of the contract.
     This can be used in inline assembly to build custom creation routines,
     especially by using the ``create2`` opcode.
     This property can **not** be accessed in the contract itself or any
     derived contract. It causes the bytecode to be included in the bytecode
     of the call site and thus circular references like that are not possible.
 
-``type(C).runtimeCode``:
+``type(C).runtimeCode``
     Memory byte array that contains the runtime bytecode of the contract.
     This is the code that is usually deployed by the constructor of ``C``.
     If ``C`` has a constructor that uses inline assembly, this might be

docs/using-the-compiler.rst

@@ -106,7 +106,8 @@ Target options
 Below is a list of target EVM versions and the compiler-relevant changes introduced
 at each version. Backward compatibility is not guaranteed between each version.
 
-- ``homestead`` (oldest version)
+- ``homestead``
+   - (oldest version)
 - ``tangerineWhistle``
    - Gas cost for access to other accounts increased, relevant for gas estimation and the optimizer.
    - All gas sent by default for external calls, previously a certain amount had to be retained.
@@ -692,7 +693,7 @@ Review changes
 
 The command above applies all changes as shown below. Please review them carefully.
 
-.. code-block:: none
+.. code-block:: solidity
 
     pragma solidity >=0.6.0 <0.7.0;