docs: fix formatting errors and style inconsistencies

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
@@ -237,7 +237,7 @@ A contract can have at most one ``receive`` function, declared using
 This function cannot have arguments, cannot return anything and must have
 ``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
@@ -245,7 +245,7 @@ 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`)
+    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`.
+    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
+used then the Solidity compiler will interpret a ``///`` or ``/**`` comment
-in the same way as if it were tagged with `@notice`.
+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
+More than one space around an assignment or other operator to align with another:
-  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
+of one or multiple lines starting with ``///`` or a
-multiline comment starting with `/**` and ending with `*/`.
+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
 

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,15 +140,19 @@ 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,
@@ -156,32 +160,32 @@ more details on error handling and when to use which function.
 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
+    * ``r`` = first 32 bytes of signature
-    ``s`` = second 32 bytes of signature
+    * ``s`` = second 32 bytes of signature
-    ``v`` = final 1 byte 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,10 +299,10 @@ 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.
@@ -301,7 +310,7 @@ available for a contract type ``C``:
     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;