migrate content to format for new docs site

Squashed commit of the following:

commit fcf35eb806100de300bd9803ce3150dde1ecc424
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 17 17:16:04 2019 -0300

    remove all docsite dependency

commit eeaee9a9d43d70704f6ab17b5126ddbd52b93a50
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 17 17:15:23 2019 -0300

    update solidity-docgen

commit f021ff951829ea0c155186749819403c6b76e803
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 17 17:05:06 2019 -0300

    update docsite script for new setup

commit ff887699d381cfbbe3acf1f1c0de8e22b58480f3
Merge: c938aa1d 84f85a41
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 17 16:46:46 2019 -0300

    Merge branch 'master' into antora

commit c938aa1d9ed05ac83a34e2cebd8353f8331ad6d6
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Jul 16 18:24:29 2019 -0300

    make component name shorter

commit 5bbd6931e02cbbd8864c82655ad0f390ceead5f3
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 10 20:16:17 2019 -0300

    add all info to docs templates

commit 39682c4515d7cf0f0368ed557f50d2709174208a
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 10 20:13:49 2019 -0300

    fix npm docsite script

commit 7ae46bd4a0437abf66150d54d05adf46e3de2cab
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 10 18:48:05 2019 -0300

    convert inline docs to asciidoc

commit cfdfd3dee4b4bf582fde22c8cb6e17a603d6e0c8
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 10 17:34:52 2019 -0300

    add missing contract names in readmes

commit 15b6a2f9bfb546cf1d3bf4f104278b118bf1b3f4
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 10 17:16:47 2019 -0300

    fix script path

commit 80d82b909f9460d1450d401f00b3f309da506b29
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 10 17:13:53 2019 -0300

    update version of solidity-docgen

commit a870b6c607b9c2d0012f8a60a4ed1a1c8b7e8ebd
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 10 17:03:53 2019 -0300

    add nav generation of api ref

commit 069cff4a25b83752650b54b86d85608c2f547e5e
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Wed Jul 10 16:32:14 2019 -0300

    initial migration to asciidoc and new docgen version

commit 55216eed0a6551da913c8d1da4b2a0d0d3faa1a8
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Jun 25 20:39:35 2019 -0300

    add basic api doc example

commit 0cbe50ce2173b6d1d9a698329d91220f58822a53
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Jun 25 19:31:31 2019 -0300

    add sidebars

commit 256fc942845307258ac9dc25aace48117fa10f79
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Jun 25 15:22:38 2019 -0300

    add page titles

commit f4d0effa70e1fc0662729863e8ee72a8821bc458
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Jun 25 15:19:41 2019 -0300

    add contracts index file

commit b73b06359979f7d933df7f2b283c50cb1c31b2a0
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Jun 25 15:14:52 2019 -0300

    fix header levels

commit fb57d9b820f09a1b7c04eed1a205be0e45866cac
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Jun 25 15:11:47 2019 -0300

    switch format to preferred asciidoctor format

commit 032181d8804137332c71534753929d080a31a71f
Author: Francisco Giordano <frangio.1@gmail.com>
Date:   Tue Jun 25 15:05:38 2019 -0300

    initialize antora component and convert docs to asciidoc

.gitignore

@@ -41,6 +41,6 @@ build/
 # IntelliJ IDE
 .idea
 
-# docsite artifacts
-docsite-build
-docs/api
+# docs artifacts
+docs/modules/api
+openzeppelin-docs

contracts/access/README.adoc

+= Access
+
+NOTE: This page is incomplete. We're working to improve it for the next release. Stay tuned!
+
+== Library
+
+{{Roles}}
+
+== Roles
+
+{{CapperRole}}
+
+{{MinterRole}}
+
+{{PauserRole}}
+
+{{SignerRole}}
+
+{{WhitelistAdminRole}}
+
+{{WhitelistedRole}}

contracts/access/README.md

----
-sections:
-  - title: Library
-    contracts:
-      - Roles
-  - subdirectory: roles
----
-
-> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/crowdsale/README.adoc

+= Crowdsales
+
+NOTE: This page is incomplete. We're working to improve it for the next release. Stay tuned!
+
+== Core
+
+{{Crowdsale}}
+
+== Emission
+
+{{AllowanceCrowdsale}}
+
+{{MintedCrowdsale}}
+
+== Validation
+
+{{CappedCrowdsale}}
+
+{{IndividuallyCappedCrowdsale}}
+
+{{PausableCrowdsale}}
+
+{{TimedCrowdsale}}
+
+{{WhitelistCrowdsale}}
+
+== Distribution
+
+{{FinalizableCrowdsale}}
+
+{{PostDeliveryCrowdsale}}
+
+{{RefundableCrowdsale}}
+
+{{RefundablePostDeliveryCrowdsale}}

contracts/crowdsale/README.md

----
-title: Crowdsales
-sections:
-  - title: Core
-    contracts:
-      - Crowdsale
-  - subdirectory: emission
-  - subdirectory: price
-  - subdirectory: validation
-  - subdirectory: distribution
----
-
-> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/cryptography/ECDSA.sol

@@ -15,15 +15,15 @@ library ECDSA {
      * this function rejects them by requiring the `s` value to be in the lower
      * half order, and the `v` value to be either 27 or 28.
      *
-     * (.note) This call _does not revert_ if the signature is invalid, or
+     * NOTE: This call _does not revert_ if the signature is invalid, or
      * if the signer is otherwise unable to be retrieved. In those scenarios,
      * the zero address is returned.
      *
-     * (.warning) `hash` _must_ be the result of a hash operation for the
+     * IMPORTANT: `hash` _must_ be the result of a hash operation for the
      * verification to be secure: it is possible to craft signatures that
      * recover to arbitrary addresses for non-hashed data. A safe way to ensure
      * this is by receiving a hash of the original message (which may otherwise)
-     * be too long), and then calling `toEthSignedMessageHash` on it.
+     * be too long), and then calling {toEthSignedMessageHash} on it.
      */
     function recover(bytes32 hash, bytes memory signature) internal pure returns (address) {
         // Check the signature length
@@ -69,10 +69,10 @@ library ECDSA {
     /**
      * @dev Returns an Ethereum Signed Message, created from a `hash`. This
      * replicates the behavior of the
-     * [`eth_sign`](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sign)
+     * https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sign[`eth_sign`]
      * JSON-RPC method.
      *
-     * See `recover`.
+     * See {recover}.
      */
     function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32) {
         // 32 is the length in bytes of hash,

contracts/cryptography/README.adoc

+= Cryptography
+
+This collection of libraries provides simple and safe ways to use different cryptographic primitives.
+
+== Libraries
+
+{{ECDSA}}
+
+{{MerkleProof}}

contracts/cryptography/README.md

----
-sections:
-  - title: Libraries
-    contracts:
-      - ECDSA
-      - MerkleProof
----
-
-This collection of libraries provides simple and safe ways to use different cryptographic primitives.

contracts/drafts/Counters.sol

@@ -9,7 +9,7 @@ import "../math/SafeMath.sol";
  * of elements in a mapping, issuing ERC721 ids, or counting request ids.
  *
  * Include with `using Counters for Counters.Counter;`
- * Since it is not possible to overflow a 256 bit integer with increments of one, `increment` can skip the SafeMath
+ * Since it is not possible to overflow a 256 bit integer with increments of one, `increment` can skip the {SafeMath}
  * overflow check, thereby saving gas. This does assume however correct usage, in that the underlying `_value` is never
  * directly accessed.
  */

contracts/drafts/ERC1046/ERC20Metadata.sol

@@ -5,7 +5,7 @@ import "../../token/ERC20/IERC20.sol";
 /**
  * @title ERC-1047 Token Metadata
  * @dev See https://eips.ethereum.org/EIPS/eip-1046
- * @dev tokenURI must respond with a URI that implements https://eips.ethereum.org/EIPS/eip-1047
+ * @dev {tokenURI} must respond with a URI that implements https://eips.ethereum.org/EIPS/eip-1047
  */
 contract ERC20Metadata {
     string private _tokenURI;

contracts/drafts/ERC20Migrator.sol

@@ -14,8 +14,8 @@ import "../math/Math.sol";
  * migration to the new token contract. In this way, token holders "turn in"
  * their old balance and will be minted an equal amount in the new token.
  * The new token contract must be mintable. For the precise interface refer to
- * OpenZeppelin's ERC20Mintable, but the only functions that are needed are
- * `isMinter(address)` and `mint(address, amount)`. The migrator will check
+ * OpenZeppelin's {ERC20Mintable}, but the only functions that are needed are
+ * {MinterRole-isMinter} and {ERC20Mintable-mint}. The migrator will check
  * that it is a minter for the token.
  * The balance from the legacy token will be transferred to the migrator, as it
  * is migrated, and remain there forever.
@@ -24,6 +24,7 @@ import "../math/Math.sol";
  * version of it using ZeppelinOS. To read more about how this can be done
  * using this implementation, please follow the official documentation site of
  * ZeppelinOS: https://docs.zeppelinos.org/docs/erc20_onboarding.html
+ *
  * Example of usage:
  * ```
  * const migrator = await ERC20Migrator.new(legacyToken.address);

contracts/drafts/ERC20Snapshot.sol

@@ -7,14 +7,16 @@ import "../token/ERC20/ERC20.sol";
 
 /**
  * @title ERC20 token with snapshots.
- * @dev Inspired by Jordi Baylina's MiniMeToken to record historical balances:
- * https://github.com/Giveth/minime/blob/ea04d950eea153a04c51fa510b068b9dded390cb/contracts/MiniMeToken.sol
- * When a snapshot is made, the balances and totalSupply at the time of the snapshot are recorded for later
+ * @dev Inspired by Jordi Baylina's
+ * https://github.com/Giveth/minimd/blob/ea04d950eea153a04c51fa510b068b9dded390cb/contracts/MiniMeToken.sol[MiniMeToken]
+ * to record historical balances.
+ *
+ * When a snapshot is made, the balances and total supply at the time of the snapshot are recorded for later
  * access.
  *
- * To make a snapshot, call the `snapshot` function, which will emit the `Snapshot` event and return a snapshot id.
- * To get the total supply from a snapshot, call the function `totalSupplyAt` with the snapshot id.
- * To get the balance of an account from a snapshot, call the `balanceOfAt` function with the snapshot id and the
+ * To make a snapshot, call the {snapshot} function, which will emit the {Snapshot} event and return a snapshot id.
+ * To get the total supply from a snapshot, call the function {totalSupplyAt} with the snapshot id.
+ * To get the balance of an account from a snapshot, call the {balanceOfAt} function with the snapshot id and the
  * account address.
  * @author Validity Labs AG <info@validitylabs.org>
  */

contracts/drafts/README.adoc

+= Drafts
+
+NOTE: This page is incomplete. We're working to improve it for the next release. Stay tuned!
+
+== ERC 20
+
+{{ERC20Migrator}}
+
+{{ERC20Snapshot}}
+
+{{TokenVesting}}
+
+== Miscellaneous
+
+{{Counters}}
+
+{{SignatureBouncer}}
+
+{{SignedSafeMath}}
+
+== ERC 1046
+
+{{ERC1046}}

contracts/drafts/README.md

----
-sections:
-  - title: ERC 20
-    contracts:
-    - ERC20Migrator
-    - ERC20Snapshot
-    - TokenVesting
-  - title: Miscellenous
-    contracts:
-    - Counters
-    - SignatureBouncer
-    - SignedSafeMath
-  - subdirectory: ERC1046
----
-
-> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/drafts/Strings.sol

@@ -6,13 +6,7 @@ pragma solidity ^0.5.0;
  */
 library Strings {
     /**
-     * Concatenates two strings.
-     * string(abi.encodePacked(a, b))
-     * https://solidity.readthedocs.io/en/latest/types.html?highlight=concatenate
-     */
-
-    /**
-     * @dev Converts a uint256 to a string.
+     * @dev Converts a `uint256` to a `string`.
      * via OraclizeAPI - MIT licence
      * https://github.com/oraclize/ethereum-api/blob/b42146b063c7d6ee1358846c198246239e9360e8/oraclizeAPI_0.4.25.sol
      */

contracts/introspection/ERC165.sol

@@ -3,9 +3,9 @@ pragma solidity ^0.5.0;
 import "./IERC165.sol";
 
 /**
- * @dev Implementation of the `IERC165` interface.
+ * @dev Implementation of the {IERC165} interface.
  *
- * Contracts may inherit from this and call `_registerInterface` to declare
+ * Contracts may inherit from this and call {_registerInterface} to declare
  * their support of an interface.
  */
 contract ERC165 is IERC165 {
@@ -26,7 +26,7 @@ contract ERC165 is IERC165 {
     }
 
     /**
-     * @dev See `IERC165.supportsInterface`.
+     * @dev See {IERC165-supportsInterface}.
      *
      * Time complexity O(1), guaranteed to always use less than 30 000 gas.
      */
@@ -39,7 +39,7 @@ contract ERC165 is IERC165 {
      * `interfaceId`. Support of the actual ERC165 interface is automatic and
      * registering its interface id is not required.
      *
-     * See `IERC165.supportsInterface`.
+     * See {IERC165-supportsInterface}.
      *
      * Requirements:
      *

contracts/introspection/ERC165Checker.sol

 pragma solidity ^0.5.0;
 
 /**
- * @dev Library used to query support of an interface declared via `IERC165`.
+ * @dev Library used to query support of an interface declared via {IERC165}.
  *
  * Note that these functions return the actual result of the query: they do not
  * `revert` if an interface is not supported. It is up to the caller to decide
@@ -17,7 +17,7 @@ library ERC165Checker {
     bytes4 private constant _INTERFACE_ID_ERC165 = 0x01ffc9a7;
 
     /**
-     * @dev Returns true if `account` supports the `IERC165` interface,
+     * @dev Returns true if `account` supports the {IERC165} interface,
      */
     function _supportsERC165(address account) internal view returns (bool) {
         // Any contract that implements ERC165 must explicitly indicate support of
@@ -28,9 +28,9 @@ library ERC165Checker {
 
     /**
      * @dev Returns true if `account` supports the interface defined by
-     * `interfaceId`. Support for `IERC165` itself is queried automatically.
+     * `interfaceId`. Support for {IERC165} itself is queried automatically.
      *
-     * See `IERC165.supportsInterface`.
+     * See {IERC165-supportsInterface}.
      */
     function _supportsInterface(address account, bytes4 interfaceId) internal view returns (bool) {
         // query support of both ERC165 as per the spec and support of _interfaceId
@@ -40,12 +40,12 @@ library ERC165Checker {
 
     /**
      * @dev Returns true if `account` supports all the interfaces defined in
-     * `interfaceIds`. Support for `IERC165` itself is queried automatically.
+     * `interfaceIds`. Support for {IERC165} itself is queried automatically.
      *
      * Batch-querying can lead to gas savings by skipping repeated checks for
-     * `IERC165` support.
+     * {IERC165} support.
      *
-     * See `IERC165.supportsInterface`.
+     * See {IERC165-supportsInterface}.
      */
     function _supportsAllInterfaces(address account, bytes4[] memory interfaceIds) internal view returns (bool) {
         // query support of ERC165 itself

contracts/introspection/ERC1820Implementer.sol

@@ -3,11 +3,11 @@ pragma solidity ^0.5.0;
 import "./IERC1820Implementer.sol";
 
 /**
- * @dev Implementation of the `IERC1820Implementer` interface.
+ * @dev Implementation of the {IERC1820Implementer} interface.
  *
- * Contracts may inherit from this and call `_registerInterfaceForAddress` to
+ * Contracts may inherit from this and call {_registerInterfaceForAddress} to
  * declare their willingness to be implementers.
- * `IERC1820Registry.setInterfaceImplementer` should then be called for the
+ * {IERC1820Registry-setInterfaceImplementer} should then be called for the
  * registration to be complete.
  */
 contract ERC1820Implementer is IERC1820Implementer {
@@ -16,7 +16,7 @@ contract ERC1820Implementer is IERC1820Implementer {
     mapping(bytes32 => mapping(address => bool)) private _supportedInterfaces;
 
     /**
-     * See `IERC1820Implementer.canImplementInterfaceForAddress`.
+     * See {IERC1820Implementer-canImplementInterfaceForAddress}.
      */
     function canImplementInterfaceForAddress(bytes32 interfaceHash, address account) external view returns (bytes32) {
         return _supportedInterfaces[interfaceHash][account] ? ERC1820_ACCEPT_MAGIC : bytes32(0x00);
@@ -26,8 +26,8 @@ contract ERC1820Implementer is IERC1820Implementer {
      * @dev Declares the contract as willing to be an implementer of
      * `interfaceHash` for `account`.
      *
-     * See `IERC1820Registry.setInterfaceImplementer` and
-     * `IERC1820Registry.interfaceHash`.
+     * See {IERC1820Registry-setInterfaceImplementer} and
+     * {IERC1820Registry-interfaceHash}.
      */
     function _registerInterfaceForAddress(bytes32 interfaceHash, address account) internal {
         _supportedInterfaces[interfaceHash][account] = true;

contracts/introspection/IERC165.sol

@@ -2,18 +2,18 @@ pragma solidity ^0.5.0;
 
 /**
  * @dev Interface of the ERC165 standard, as defined in the
- * [EIP](https://eips.ethereum.org/EIPS/eip-165).
+ * https://eips.ethereum.org/EIPS/eip-165[EIP].
  *
  * Implementers can declare support of contract interfaces, which can then be
- * queried by others (`ERC165Checker`).
+ * queried by others ({ERC165Checker}).
  *
- * For an implementation, see `ERC165`.
+ * For an implementation, see {ERC165}.
  */
 interface IERC165 {
     /**
      * @dev Returns true if this contract implements the interface defined by
      * `interfaceId`. See the corresponding
-     * [EIP section](https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified)
+     * https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section]
      * to learn more about how these ids are created.
      *
      * This function call must use less than 30 000 gas.

contracts/introspection/IERC1820Implementer.sol

@@ -2,16 +2,16 @@ pragma solidity ^0.5.0;
 
 /**
  * @dev Interface for an ERC1820 implementer, as defined in the
- * [EIP](https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface).
+ * https://eips.ethereum.org/EIPS/eip-1820#interface-implementation-erc1820implementerinterface[EIP].
  * Used by contracts that will be registered as implementers in the
- * `IERC1820Registry`.
+ * {IERC1820Registry}.
  */
 interface IERC1820Implementer {
     /**
      * @dev Returns a special value (`ERC1820_ACCEPT_MAGIC`) if this contract
      * implements `interfaceHash` for `account`.
      *
-     * See `IERC1820Registry.setInterfaceImplementer`.
+     * See {IERC1820Registry-setInterfaceImplementer}.
      */
     function canImplementInterfaceForAddress(bytes32 interfaceHash, address account) external view returns (bytes32);
 }

contracts/introspection/IERC1820Registry.sol

@@ -2,7 +2,7 @@ pragma solidity ^0.5.0;
 
 /**
  * @dev Interface of the global ERC1820 Registry, as defined in the
- * [EIP](https://eips.ethereum.org/EIPS/eip-1820). Accounts may register
+ * https://eips.ethereum.org/EIPS/eip-1820[EIP]. Accounts may register
  * implementers for interfaces in this registry, as well as query support.
  *
  * Implementers may be shared by multiple accounts, and can also implement more
@@ -10,7 +10,7 @@ pragma solidity ^0.5.0;
  * for themselves, but externally-owned accounts (EOA) must delegate this to a
  * contract.
  *
- * `IERC165` interfaces can also be queried via the registry.
+ * {IERC165} interfaces can also be queried via the registry.
  *
  * For an in-depth explanation and source code analysis, see the EIP text.
  */
@@ -22,7 +22,7 @@ interface IERC1820Registry {
      * By default, each account is its own manager. Passing a value of `0x0` in
      * `newManager` will reset the manager to this initial state.
      *
-     * Emits a `ManagerChanged` event.
+     * Emits a {ManagerChanged} event.
      *
      * Requirements:
      *
@@ -33,7 +33,7 @@ interface IERC1820Registry {
     /**
      * @dev Returns the manager for `account`.
      *
-     * See `setManager`.
+     * See {setManager}.
      */
     function getManager(address account) external view returns (address);
 
@@ -44,18 +44,18 @@ interface IERC1820Registry {
      * `account` being the zero address is an alias for the caller's address.
      * The zero address can also be used in `implementer` to remove an old one.
      *
-     * See `interfaceHash` to learn how these are created.
+     * See {interfaceHash} to learn how these are created.
      *
-     * Emits an `InterfaceImplementerSet` event.
+     * Emits an {InterfaceImplementerSet} event.
      *
      * Requirements:
      *
      * - the caller must be the current manager for `account`.
-     * - `interfaceHash` must not be an `IERC165` interface id (i.e. it must not
+     * - `interfaceHash` must not be an {IERC165} interface id (i.e. it must not
      * end in 28 zeroes).
-     * - `implementer` must implement `IERC1820Implementer` and return true when
+     * - `implementer` must implement {IERC1820Implementer} and return true when
      * queried for support, unless `implementer` is the caller. See
-     * `IERC1820Implementer.canImplementInterfaceForAddress`.
+     * {IERC1820Implementer-canImplementInterfaceForAddress}.
      */
     function setInterfaceImplementer(address account, bytes32 interfaceHash, address implementer) external;
 
@@ -63,7 +63,7 @@ interface IERC1820Registry {
      * @dev Returns the implementer of `interfaceHash` for `account`. If no such
      * implementer is registered, returns the zero address.
      *
-     * If `interfaceHash` is an `IERC165` interface id (i.e. it ends with 28
+     * If `interfaceHash` is an {IERC165} interface id (i.e. it ends with 28
      * zeroes), `account` will be queried for support of it.
      *
      * `account` being the zero address is an alias for the caller's address.
@@ -73,7 +73,7 @@ interface IERC1820Registry {
     /**
      * @dev Returns the interface hash for an `interfaceName`, as defined in the
      * corresponding
-     * [section of the EIP](https://eips.ethereum.org/EIPS/eip-1820#interface-name).
+     * https://eips.ethereum.org/EIPS/eip-1820#interface-name[section of the EIP].
      */
     function interfaceHash(string calldata interfaceName) external pure returns (bytes32);
 
@@ -88,10 +88,10 @@ interface IERC1820Registry {
      *  @notice Checks whether a contract implements an ERC165 interface or not.
      *  If the result is not cached a direct lookup on the contract address is performed.
      *  If the result is not cached or the cached value is out-of-date, the cache MUST be updated manually by calling
-     *  'updateERC165Cache' with the contract address.
+     *  {updateERC165Cache} with the contract address.
      *  @param account Address of the contract to check.
      *  @param interfaceId ERC165 interface to check.
-     *  @return True if `account.address()` implements `interfaceId`, false otherwise.
+     *  @return True if `account` implements `interfaceId`, false otherwise.
      */
     function implementsERC165Interface(address account, bytes4 interfaceId) external view returns (bool);
 
@@ -99,7 +99,7 @@ interface IERC1820Registry {
      *  @notice Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.
      *  @param account Address of the contract to check.
      *  @param interfaceId ERC165 interface to check.
-     *  @return True if `account.address()` implements `interfaceId`, false otherwise.
+     *  @return True if `account` implements `interfaceId`, false otherwise.
      */
     function implementsERC165InterfaceNoCache(address account, bytes4 interfaceId) external view returns (bool);
 

contracts/introspection/README.md → contracts/introspection/README.adoc

----
-sections:
-  - title: Local
-    contracts:
-      - IERC165
-      - ERC165
-      - ERC165Checker
-  - title: Global
-    contracts:
-      - IERC1820Registry
-      - IERC1820Implementer
-      - ERC1820Implementer
----
+= Introspection
 
 This set of interfaces and contracts deal with [type introspection](https://en.wikipedia.org/wiki/Type_introspection) of contracts, that is, examining which functions can be called on them. This is usually referred to as a contract's _interface_.
 
@@ -21,3 +9,19 @@ There are two main ways to approach this.
  - Globally, where a global and unique registry (`IERC1820Registry`) is used to register implementers of a certain interface (`IERC1820Implementer`). It is then the registry that is queried, which allows for more complex setups, like contracts implementing interfaces for externally-owned accounts.
 
 Note that, in all cases, accounts simply _declare_ their interfaces, but they are not required to actually implement them. This mechanism can therefore be used to both prevent errors and allow for complex interactions (see `ERC777`), but it must not be relied on for security.
+
+== Local
+
+{{IERC165}}
+
+{{ERC165}}
+
+{{ERC165Checker}}
+
+== Global
+
+{{IERC1820Registry}}
+
+{{IERC1820Implementer}}
+
+{{ERC1820Implementer}}

contracts/math/README.adoc

+= Math
+
+These are math-related utilities.
+
+== Libraries
+
+{{SafeMath}}
+
+{{Math}}

contracts/math/README.md

----
-title: Math
-sections:
-  - title: Libraries
-    contracts:
-      - SafeMath
-      - Math
----
-
-These are math-related utilities.

contracts/ownership/Ownable.sol

@@ -48,7 +48,7 @@ contract Ownable {
      * @dev Leaves the contract without owner. It will not be possible to call
      * `onlyOwner` functions anymore. Can only be called by the current owner.
      *
-     * > Note: Renouncing ownership will leave the contract without an owner,
+     * NOTE: Renouncing ownership will leave the contract without an owner,
      * thereby removing any functionality that is only available to the owner.
      */
     function renounceOwnership() public onlyOwner {

contracts/ownership/README.adoc

+= Ownership
+
+Contract modules for simple authorization and access control mechanisms.
+
+TIP: For more complex needs see xref:access.adoc.
+
+{{Ownable}}
+
+{{Secondary}}

contracts/ownership/README.md

-Contract modules for simple authorization and access control mechanisms.
-
-For more complex needs see [Access](access).

contracts/payment/PaymentSplitter.sol

@@ -12,7 +12,7 @@ import "../math/SafeMath.sol";
  * an amount proportional to the percentage of total shares they were assigned.
  *
  * `PaymentSplitter` follows a _pull payment_ model. This means that payments are not automatically forwarded to the
- * accounts but kept in this contract, and the actual transfer is triggered as a separate step by calling the `release`
+ * accounts but kept in this contract, and the actual transfer is triggered as a separate step by calling the {release}
  * function.
  */
 contract PaymentSplitter {
@@ -47,13 +47,13 @@ contract PaymentSplitter {
     }
 
     /**
-     * @dev The Ether received will be logged with `PaymentReceived` events. Note that these events are not fully
+     * @dev The Ether received will be logged with {PaymentReceived} events. Note that these events are not fully
      * reliable: it's possible for a contract to receive Ether without triggering this function. This only affects the
      * reliability of the events, and not the actual splitting of Ether.
      *
-     * To learn more about this see the Solidity documentation for [fallback functions].
-     *
-     * [fallback functions]: https://solidity.readthedocs.io/en/latest/contracts.html#fallback-function
+     * To learn more about this see the Solidity documentation for
+     * https://solidity.readthedocs.io/en/latest/contracts.html#fallback-function[fallback
+     * functions].
      */
     function () external payable {
         emit PaymentReceived(msg.sender, msg.value);

contracts/payment/PullPayment.sol

@@ -5,7 +5,7 @@ import "./escrow/Escrow.sol";
 /**
  * @title PullPayment
  * @dev Base contract supporting async send for pull payments. Inherit from this
- * contract and use _asyncTransfer instead of send or transfer.
+ * contract and use {_asyncTransfer} instead of send or transfer.
  */
 contract PullPayment {
     Escrow private _escrow;

contracts/payment/README.adoc

+= Payment
+
+NOTE: This page is incomplete. We're working to improve it for the next release. Stay tuned!
+
+== Utilities
+
+{{PaymentSplitter}}
+
+{{PullPayment}}
+
+== Escrow
+
+{{Escrow}}
+
+{{ConditionalEscrow}}
+
+{{RefundEscrow}}

contracts/payment/README.md

----
-sections:
-  - title: Payment Utilities
-    contracts:
-      - PaymentSplitter
-      - PullPayment
-  - subdirectory: escrow
----
-
-> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/payment/escrow/ConditionalEscrow.sol

@@ -5,7 +5,7 @@ import "./Escrow.sol";
 /**
  * @title ConditionalEscrow
  * @dev Base abstract escrow to only allow withdrawal if a condition is met.
- * @dev Intended usage: See Escrow.sol. Same usage guidelines apply here.
+ * @dev Intended usage: See {Escrow}. Same usage guidelines apply here.
  */
 contract ConditionalEscrow is Escrow {
     /**

contracts/payment/escrow/Escrow.sol

@@ -7,10 +7,11 @@ import "../../ownership/Secondary.sol";
   * @title Escrow
   * @dev Base escrow contract, holds funds designated for a payee until they
   * withdraw them.
-  * @dev Intended usage: This contract (and derived escrow contracts) should be a
+  *
+  * Intended usage: This contract (and derived escrow contracts) should be a
   * standalone contract, that only interacts with the contract that instantiated
   * it. That way, it is guaranteed that all Ether will be handled according to
-  * the Escrow rules, and there is no need to check for payable functions or
+  * the `Escrow` rules, and there is no need to check for payable functions or
   * transfers in the inheritance tree. The contract that uses the escrow as its
   * payment method should be its primary, and provide public methods redirecting
   * to the escrow's deposit and withdraw.

contracts/payment/escrow/README.md

----
-title: Escrows
-sections:
-  - contracts:
-    - Escrow
-    - ConditionalEscrow
-    - RefundEscrow
----

contracts/payment/escrow/RefundEscrow.sol

@@ -6,12 +6,12 @@ import "./ConditionalEscrow.sol";
  * @title RefundEscrow
  * @dev Escrow that holds funds for a beneficiary, deposited from multiple
  * parties.
- * @dev Intended usage: See Escrow.sol. Same usage guidelines apply here.
+ * @dev Intended usage: See {Escrow}. Same usage guidelines apply here.
  * @dev The primary account (that is, the contract that instantiates this
  * contract) may deposit, close the deposit period, and allow for either
  * withdrawal by the beneficiary, or refunds to the depositors. All interactions
- * with RefundEscrow will be made through the primary contract. See the
- * RefundableCrowdsale contract for an example of RefundEscrow’s use.
+ * with `RefundEscrow` will be made through the primary contract. See the
+ * `RefundableCrowdsale` contract for an example of `RefundEscrow`’s use.
  */
 contract RefundEscrow is ConditionalEscrow {
     enum State { Active, Refunding, Closed }

contracts/token/ERC20/ERC20.sol

@@ -4,27 +4,28 @@ import "./IERC20.sol";
 import "../../math/SafeMath.sol";
 
 /**
- * @dev Implementation of the `IERC20` interface.
+ * @dev Implementation of the {IERC20} interface.
  *
  * This implementation is agnostic to the way tokens are created. This means
- * that a supply mechanism has to be added in a derived contract using `_mint`.
- * For a generic mechanism see `ERC20Mintable`.
+ * that a supply mechanism has to be added in a derived contract using {_mint}.
+ * For a generic mechanism see {ERC20Mintable}.
  *
- * *For a detailed writeup see our guide [How to implement supply
- * mechanisms](https://forum.zeppelin.solutions/t/how-to-implement-erc20-supply-mechanisms/226).*
+ * TIP: For a detailed writeup see our guide
+ * https://forum.zeppelin.solutions/t/how-to-implement-erc20-supply-mechanisms/226[How
+ * to implement supply mechanisms].
  *
  * We have followed general OpenZeppelin guidelines: functions revert instead
  * of returning `false` on failure. This behavior is nonetheless conventional
  * and does not conflict with the expectations of ERC20 applications.
  *
- * Additionally, an `Approval` event is emitted on calls to `transferFrom`.
+ * Additionally, an {Approval} event is emitted on calls to {transferFrom}.
  * This allows applications to reconstruct the allowance for all accounts just
  * by listening to said events. Other implementations of the EIP may not emit
  * these events, as it isn't required by the specification.
  *
- * Finally, the non-standard `decreaseAllowance` and `increaseAllowance`
+ * Finally, the non-standard {decreaseAllowance} and {increaseAllowance}
  * functions have been added to mitigate the well-known issues around setting
- * allowances. See `IERC20.approve`.
+ * allowances. See {IERC20-approve}.
  */
 contract ERC20 is IERC20 {
     using SafeMath for uint256;
@@ -36,21 +37,21 @@ contract ERC20 is IERC20 {
     uint256 private _totalSupply;
 
     /**
-     * @dev See `IERC20.totalSupply`.
+     * @dev See {IERC20-totalSupply}.
      */
     function totalSupply() public view returns (uint256) {
         return _totalSupply;
     }
 
     /**
-     * @dev See `IERC20.balanceOf`.
+     * @dev See {IERC20-balanceOf}.
      */
     function balanceOf(address account) public view returns (uint256) {
         return _balances[account];
     }
 
     /**
-     * @dev See `IERC20.transfer`.
+     * @dev See {IERC20-transfer}.
      *
      * Requirements:
      *
@@ -63,14 +64,14 @@ contract ERC20 is IERC20 {
     }
 
     /**
-     * @dev See `IERC20.allowance`.
+     * @dev See {IERC20-allowance}.
      */
     function allowance(address owner, address spender) public view returns (uint256) {
         return _allowances[owner][spender];
     }
 
     /**
-     * @dev See `IERC20.approve`.
+     * @dev See {IERC20-approve}.
      *
      * Requirements:
      *
@@ -82,10 +83,10 @@ contract ERC20 is IERC20 {
     }
 
     /**
-     * @dev See `IERC20.transferFrom`.
+     * @dev See {IERC20-transferFrom}.
      *
-     * Emits an `Approval` event indicating the updated allowance. This is not
-     * required by the EIP. See the note at the beginning of `ERC20`;
+     * Emits an {Approval} event indicating the updated allowance. This is not
+     * required by the EIP. See the note at the beginning of {ERC20};
      *
      * Requirements:
      * - `sender` and `recipient` cannot be the zero address.
@@ -102,10 +103,10 @@ contract ERC20 is IERC20 {
     /**
      * @dev Atomically increases the allowance granted to `spender` by the caller.
      *
-     * This is an alternative to `approve` that can be used as a mitigation for
-     * problems described in `IERC20.approve`.
+     * This is an alternative to {approve} that can be used as a mitigation for
+     * problems described in {IERC20-approve}.
      *
-     * Emits an `Approval` event indicating the updated allowance.
+     * Emits an {Approval} event indicating the updated allowance.
      *
      * Requirements:
      *
@@ -119,10 +120,10 @@ contract ERC20 is IERC20 {
     /**
      * @dev Atomically decreases the allowance granted to `spender` by the caller.
      *
-     * This is an alternative to `approve` that can be used as a mitigation for
-     * problems described in `IERC20.approve`.
+     * This is an alternative to {approve} that can be used as a mitigation for
+     * problems described in {IERC20-approve}.
      *
-     * Emits an `Approval` event indicating the updated allowance.
+     * Emits an {Approval} event indicating the updated allowance.
      *
      * Requirements:
      *
@@ -138,10 +139,10 @@ contract ERC20 is IERC20 {
     /**
      * @dev Moves tokens `amount` from `sender` to `recipient`.
      *
-     * This is internal function is equivalent to `transfer`, and can be used to
+     * This is internal function is equivalent to {transfer}, and can be used to
      * e.g. implement automatic token fees, slashing mechanisms, etc.
      *
-     * Emits a `Transfer` event.
+     * Emits a {Transfer} event.
      *
      * Requirements:
      *
@@ -161,7 +162,7 @@ contract ERC20 is IERC20 {
     /** @dev Creates `amount` tokens and assigns them to `account`, increasing
      * the total supply.
      *
-     * Emits a `Transfer` event with `from` set to the zero address.
+     * Emits a {Transfer} event with `from` set to the zero address.
      *
      * Requirements
      *
@@ -179,7 +180,7 @@ contract ERC20 is IERC20 {
      * @dev Destroys `amount` tokens from `account`, reducing the
      * total supply.
      *
-     * Emits a `Transfer` event with `to` set to the zero address.
+     * Emits a {Transfer} event with `to` set to the zero address.
      *
      * Requirements
      *
@@ -200,7 +201,7 @@ contract ERC20 is IERC20 {
      * This is internal function is equivalent to `approve`, and can be used to
      * e.g. set automatic allowances for certain subsystems, etc.
      *
-     * Emits an `Approval` event.
+     * Emits an {Approval} event.
      *
      * Requirements:
      *
@@ -219,7 +220,7 @@ contract ERC20 is IERC20 {
      * @dev Destoys `amount` tokens from `account`.`amount` is then deducted
      * from the caller's allowance.
      *
-     * See `_burn` and `_approve`.
+     * See {_burn} and {_approve}.
      */
     function _burnFrom(address account, uint256 amount) internal {
         _burn(account, amount);

contracts/token/ERC20/ERC20Burnable.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.5.0;
 import "./ERC20.sol";
 
 /**
- * @dev Extension of `ERC20` that allows token holders to destroy both their own
+ * @dev Extension of {ERC20} that allows token holders to destroy both their own
  * tokens and those that they have an allowance for, in a way that can be
  * recognized off-chain (via event analysis).
  */
@@ -11,14 +11,14 @@ contract ERC20Burnable is ERC20 {
     /**
      * @dev Destroys `amount` tokens from the caller.
      *
-     * See `ERC20._burn`.
+     * See {ERC20-_burn}.
      */
     function burn(uint256 amount) public {
         _burn(msg.sender, amount);
     }
 
     /**
-     * @dev See `ERC20._burnFrom`.
+     * @dev See {ERC20-_burnFrom}.
      */
     function burnFrom(address account, uint256 amount) public {
         _burnFrom(account, amount);

contracts/token/ERC20/ERC20Capped.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.5.0;
 import "./ERC20Mintable.sol";
 
 /**
- * @dev Extension of `ERC20Mintable` that adds a cap to the supply of tokens.
+ * @dev Extension of {ERC20Mintable} that adds a cap to the supply of tokens.
  */
 contract ERC20Capped is ERC20Mintable {
     uint256 private _cap;
@@ -25,7 +25,7 @@ contract ERC20Capped is ERC20Mintable {
     }
 
     /**
-     * @dev See `ERC20Mintable.mint`.
+     * @dev See {ERC20Mintable-mint}.
      *
      * Requirements:
      *

contracts/token/ERC20/ERC20Detailed.sol

@@ -44,9 +44,9 @@ contract ERC20Detailed is IERC20 {
      * Tokens usually opt for a value of 18, imitating the relationship between
      * Ether and Wei.
      *
-     * > Note that this information is only used for _display_ purposes: it in
+     * NOTE: This information is only used for _display_ purposes: it in
      * no way affects any of the arithmetic of the contract, including
-     * `IERC20.balanceOf` and `IERC20.transfer`.
+     * {IERC20-balanceOf} and {IERC20-transfer}.
      */
     function decimals() public view returns (uint8) {
         return _decimals;

contracts/token/ERC20/ERC20Mintable.sol

@@ -4,18 +4,18 @@ import "./ERC20.sol";
 import "../../access/roles/MinterRole.sol";
 
 /**
- * @dev Extension of `ERC20` that adds a set of accounts with the `MinterRole`,
+ * @dev Extension of {ERC20} that adds a set of accounts with the {MinterRole},
  * which have permission to mint (create) new tokens as they see fit.
  *
  * At construction, the deployer of the contract is the only minter.
  */
 contract ERC20Mintable is ERC20, MinterRole {
     /**
-     * @dev See `ERC20._mint`.
+     * @dev See {ERC20-_mint}.
      *
      * Requirements:
      *
-     * - the caller must have the `MinterRole`.
+     * - the caller must have the {MinterRole}.
      */
     function mint(address account, uint256 amount) public onlyMinter returns (bool) {
         _mint(account, amount);

contracts/token/ERC20/ERC20Pausable.sol

@@ -7,7 +7,7 @@ import "../../lifecycle/Pausable.sol";
  * @title Pausable token
  * @dev ERC20 with pausable transfers and allowances.
  *
- * Useful if you want to e.g. stop trades until the end of a crowdsale, or have
+ * Useful if you want to stop trades until the end of a crowdsale, or have
  * an emergency switch for freezing all token transfers in the event of a large
  * bug.
  */

contracts/token/ERC20/IERC20.sol

@@ -2,7 +2,7 @@ pragma solidity ^0.5.0;
 
 /**
  * @dev Interface of the ERC20 standard as defined in the EIP. Does not include
- * the optional functions; to access them see `ERC20Detailed`.
+ * the optional functions; to access them see {ERC20Detailed}.
  */
 interface IERC20 {
     /**
@@ -20,16 +20,16 @@ interface IERC20 {
      *
      * Returns a boolean value indicating whether the operation succeeded.
      *
-     * Emits a `Transfer` event.
+     * Emits a {Transfer} event.
      */
     function transfer(address recipient, uint256 amount) external returns (bool);
 
     /**
      * @dev Returns the remaining number of tokens that `spender` will be
-     * allowed to spend on behalf of `owner` through `transferFrom`. This is
+     * allowed to spend on behalf of `owner` through {transferFrom}. This is
      * zero by default.
      *
-     * This value changes when `approve` or `transferFrom` are called.
+     * This value changes when {approve} or {transferFrom} are called.
      */
     function allowance(address owner, address spender) external view returns (uint256);
 
@@ -38,14 +38,14 @@ interface IERC20 {
      *
      * Returns a boolean value indicating whether the operation succeeded.
      *
-     * > Beware that changing an allowance with this method brings the risk
+     * IMPORTANT: Beware that changing an allowance with this method brings the risk
      * that someone may use both the old and the new allowance by unfortunate
      * transaction ordering. One possible solution to mitigate this race
      * condition is to first reduce the spender's allowance to 0 and set the
      * desired value afterwards:
      * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
      *
-     * Emits an `Approval` event.
+     * Emits an {Approval} event.
      */
     function approve(address spender, uint256 amount) external returns (bool);
 
@@ -56,7 +56,7 @@ interface IERC20 {
      *
      * Returns a boolean value indicating whether the operation succeeded.
      *
-     * Emits a `Transfer` event.
+     * Emits a {Transfer} event.
      */
     function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
 
@@ -70,7 +70,7 @@ interface IERC20 {
 
     /**
      * @dev Emitted when the allowance of a `spender` for an `owner` is set by
-     * a call to `approve`. `value` is the new allowance.
+     * a call to {approve}. `value` is the new allowance.
      */
     event Approval(address indexed owner, address indexed spender, uint256 value);
 }

contracts/token/ERC20/README.adoc

+= ERC 20
+
+This set of interfaces, contracts, and utilities are all related to the https://eips.ethereum.org/EIPS/eip-20[ERC20 Token Standard].
+
+TIP: For an overview of ERC20 tokens and a walkthrough on how to create a token contract read our xref:ROOT:tokens.adoc#erc20[ERC20 guide].
+
+There a few core contracts that implement the behavior specified in the EIP:
+ - {IERC20}: the interface all ERC20 implementations should conform to
+ - {ERC20}: the base implementation of the ERC20 interface
+ - {ERC20Detailed}: includes the <<ERC20Detailed-name,`name`>>,
+   <<ERC20Detailed-symbol,`symbol`>> and <<ERC20Detailed-decimals,`decimals`>>
+   optional standard extension to the base interface
+
+Additionally there are multiple custom extensions, including:
+- designation of addresses that can create token supply ({ERC20Mintable}), with an optional maximum cap ({ERC20Capped})
+- destruction of own tokens ({ERC20Burnable})
+- designation of addresses that can pause token operations for all users ({ERC20Pausable}).
+
+Finally, there are some utilities to interact with ERC20 contracts in various ways.
+- {SafeERC20} is a wrapper around the interface that eliminates the need to handle boolean return values.
+- {TokenTimelock} can hold tokens for a beneficiary until a specified time.
+
+NOTE: This page is incomplete. We're working to improve it for the next release. Stay tuned!
+
+== Core
+
+{{IERC20}}
+
+{{ERC20}}
+
+{{ERC20Detailed}}
+
+== Extensions
+
+{{ERC20Mintable}}
+
+{{ERC20Burnable}}
+
+{{ERC20Pausable}}
+
+{{ERC20Capped}}
+
+== Utilities
+
+{{SafeERC20}}
+
+{{TokenTimelock}}

contracts/token/ERC20/README.md

----
-sections:
-  - title: Core
-    contracts:
-      - IERC20
-      - ERC20
-      - ERC20Detailed
-  - title: Extensions
-    contracts:
-      - ERC20Mintable
-      - ERC20Burnable
-      - ERC20Pausable
-      - ERC20Capped
-  - title: Utilities
-    contracts:
-      - SafeERC20
-      - TokenTimelock
----
-
-This set of interfaces, contracts, and utilities are all related to the [ERC20 Token Standard](https://eips.ethereum.org/EIPS/eip-20).
-
-*For an overview of ERC20 tokens and a walkthrough on how to create a token contract read our [ERC20 guide](../../tokens#erc20).*
-
-There a few core contracts that implement the behavior specified in the EIP:
- - `IERC20`: the interface all ERC20 implementations should conform to
- - `ERC20`: the base implementation of the ERC20 interface
- - `ERC20Detailed`: includes the `name()`, `symbol()` and `decimals()` optional standard extension to the base interface
-
-Additionally there are multiple custom extensions, including:
-- designation of addresses that can create token supply (`ERC20Mintable`), with an optional maximum cap (`ERC20Capped`)
-- destruction of own tokens (`ERC20Burnable`)
-- designation of addresses that can pause token operations for all users (`ERC20Pausable`).
-
-Finally, there are some utilities to interact with ERC20 contracts in various ways.
-- `SafeERC20` is a wrapper around the interface that eliminates the need to handle boolean return values.
-- `TokenTimelock` can hold tokens for a beneficiary until a specified time.
-
-> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/token/ERC20/TokenTimelock.sol

@@ -9,8 +9,7 @@ import "./SafeERC20.sol";
  * Useful for simple vesting schedules like "advisors get all of their tokens
  * after 1 year".
  *
- * For a more complete vesting schedule, see
- * [`TokenVesting`](api/drafts#tokenvesting).
+ * For a more complete vesting schedule, see {TokenVesting}.
  */
 contract TokenTimelock {
     using SafeERC20 for IERC20;

contracts/token/ERC721/ERC721.sol

@@ -133,7 +133,7 @@ contract ERC721 is ERC165, IERC721 {
 
     /**
      * @dev Transfers the ownership of a given token ID to another address.
-     * Usage of this method is discouraged, use `safeTransferFrom` whenever possible.
+     * Usage of this method is discouraged, use {safeTransferFrom} whenever possible.
      * Requires the msg.sender to be the owner, approved, or operator.
      * @param from current owner of the token
      * @param to address to receive the ownership of the given token ID
@@ -148,7 +148,7 @@ contract ERC721 is ERC165, IERC721 {
 
     /**
      * @dev Safely transfers the ownership of a given token ID to another address
-     * If the target address is a contract, it must implement `onERC721Received`,
+     * If the target address is a contract, it must implement {IERC721Receiver-onERC721Received},
      * which is called upon a safe transfer, and return the magic value
      * `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`; otherwise,
      * the transfer is reverted.
@@ -163,7 +163,7 @@ contract ERC721 is ERC165, IERC721 {
 
     /**
      * @dev Safely transfers the ownership of a given token ID to another address
-     * If the target address is a contract, it must implement `onERC721Received`,
+     * If the target address is a contract, it must implement {IERC721Receiver-onERC721Received},
      * which is called upon a safe transfer, and return the magic value
      * `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`; otherwise,
      * the transfer is reverted.
@@ -220,7 +220,7 @@ contract ERC721 is ERC165, IERC721 {
     /**
      * @dev Internal function to burn a specific token.
      * Reverts if the token does not exist.
-     * Deprecated, use _burn(uint256) instead.
+     * Deprecated, use {_burn} instead.
      * @param owner owner of the token to burn
      * @param tokenId uint256 ID of the token being burned
      */
@@ -246,7 +246,7 @@ contract ERC721 is ERC165, IERC721 {
 
     /**
      * @dev Internal function to transfer ownership of a given token ID to another address.
-     * As opposed to transferFrom, this imposes no restrictions on msg.sender.
+     * As opposed to {transferFrom}, this imposes no restrictions on msg.sender.
      * @param from current owner of the token
      * @param to address to receive the ownership of the given token ID
      * @param tokenId uint256 ID of the token to be transferred
@@ -266,7 +266,7 @@ contract ERC721 is ERC165, IERC721 {
     }
 
     /**
-     * @dev Internal function to invoke `onERC721Received` on a target address.
+     * @dev Internal function to invoke {IERC721Receiver-onERC721Received} on a target address.
      * The call is not executed if the target address is not a contract.
      *
      * This function is deprecated.

contracts/token/ERC721/ERC721Enumerable.sol

@@ -100,7 +100,7 @@ contract ERC721Enumerable is ERC165, ERC721, IERC721Enumerable {
     /**
      * @dev Internal function to burn a specific token.
      * Reverts if the token does not exist.
-     * Deprecated, use _burn(uint256) instead.
+     * Deprecated, use {ERC721-_burn} instead.
      * @param owner owner of the token to burn
      * @param tokenId uint256 ID of the token being burned
      */
@@ -144,7 +144,7 @@ contract ERC721Enumerable is ERC165, ERC721, IERC721Enumerable {
 
     /**
      * @dev Private function to remove a token from this extension's ownership-tracking data structures. Note that
-     * while the token is not assigned a new owner, the _ownedTokensIndex mapping is _not_ updated: this allows for
+     * while the token is not assigned a new owner, the `_ownedTokensIndex` mapping is _not_ updated: this allows for
      * gas optimizations e.g. when performing a transfer operation (avoiding double writes).
      * This has O(1) time complexity, but alters the order of the _ownedTokens array.
      * @param from address representing the previous owner of the given token ID

contracts/token/ERC721/ERC721Full.sol

@@ -6,9 +6,10 @@ import "./ERC721Metadata.sol";
 
 /**
  * @title Full ERC721 Token
- * This implementation includes all the required and some optional functionality of the ERC721 standard
- * Moreover, it includes approve all functionality using operator terminology
- * @dev see https://eips.ethereum.org/EIPS/eip-721
+ * @dev This implementation includes all the required and some optional functionality of the ERC721 standard
+ * Moreover, it includes approve all functionality using operator terminology.
+ *
+ * See https://eips.ethereum.org/EIPS/eip-721
  */
 contract ERC721Full is ERC721, ERC721Enumerable, ERC721Metadata {
     constructor (string memory name, string memory symbol) public ERC721Metadata(name, symbol) {

contracts/token/ERC721/IERC721.sol

@@ -30,7 +30,7 @@ contract IERC721 is IERC165 {
      * - `from`, `to` cannot be zero.
      * - `tokenId` must be owned by `from`.
      * - If the caller is not `from`, it must be have been allowed to move this
-     * NFT by either `approve` or `setApproveForAll`.
+     * NFT by either {approve} or {setApproveForAll}.
      */
     function safeTransferFrom(address from, address to, uint256 tokenId) public;
     /**
@@ -39,7 +39,7 @@ contract IERC721 is IERC165 {
      *
      * Requirements:
      * - If the caller is not `from`, it must be approved to move this NFT by
-     * either `approve` or `setApproveForAll`.
+     * either {approve} or {setApproveForAll}.
      */
     function transferFrom(address from, address to, uint256 tokenId) public;
     function approve(address to, uint256 tokenId) public;

contracts/token/ERC721/IERC721Receiver.sol

@@ -9,7 +9,7 @@ contract IERC721Receiver {
     /**
      * @notice Handle the receipt of an NFT
      * @dev The ERC721 smart contract calls this function on the recipient
-     * after a `safeTransfer`. This function MUST return the function selector,
+     * after a {IERC721-safeTransfer}. This function MUST return the function selector,
      * otherwise the caller will revert the transaction. The selector to be
      * returned can be obtained as `this.onERC721Received.selector`. This
      * function MAY throw to revert and reject the transfer.

contracts/token/ERC721/README.adoc

+= ERC 721
+
+This set of interfaces, contracts, and utilities are all related to the https://eips.ethereum.org/EIPS/eip-721[ERC721 Non-Fungible Token Standard].
+
+TIP: For a walkthrough on how to create an ERC721 token read our xref:ROOT:tokens.adoc#ERC721[ERC721 guide].
+
+The EIP consists of three interfaces, found here as {IERC721}, {IERC721Metadata}, and {IERC721Enumerable}. Only the first one is required in a contract to be ERC721 compliant.
+
+Each interface is implemented separately in {ERC721}, {ERC721Metadata}, and {ERC721Enumerable}. You can choose the subset of functionality you would like to support in your token by combining the
+desired subset through inheritance.
+
+The fully featured token implementing all three interfaces is prepackaged as {ERC721Full}.
+
+Additionally, {IERC721Receiver} can be used to prevent tokens from becoming forever locked in contracts. Imagine sending an in-game item to an exchange address that can't send it back!. When using <<IERC721-safeTransferFrom,`safeTransferFrom`>>, the token contract checks to see that the receiver is an {IERC721Receiver}, which implies that it knows how to handle {ERC721} tokens. If you're writing a contract that needs to receive {ERC721} tokens, you'll want to include this interface.
+
+Finally, some custom extensions are also included:
+- {ERC721Mintable} — like the ERC20 version, this allows certain addresses to mint new tokens
+- {ERC721Pausable} — like the ERC20 version, this allows addresses to freeze transfers of tokens
+
+NOTE: This page is incomplete. We're working to improve it for the next release. Stay tuned!
+
+== Core
+
+{{IERC721}}
+
+{{ERC721}}
+
+{{IERC721Metadata}}
+
+{{ERC721Metadata}}
+
+{{ERC721Enumerable}}
+
+{{IERC721Enumerable}}
+
+{{IERC721Full}}
+
+{{ERC721Full}}
+
+{{IERC721Receiver}}
+
+== Extensions
+
+{{ERC721Mintable}}
+
+{{ERC721MetadataMintable}}
+
+{{ERC721Burnable}}
+
+{{ERC721Pausable}}
+
+== Convenience
+
+{{ERC721Holder}}

contracts/token/ERC721/README.md

----
-sections:
-  - title: Core
-    contracts:
-      - IERC721
-      - ERC721
-      - IERC721Metadata
-      - ERC721Metadata
-      - ERC721Enumerable
-      - IERC721Enumerable
-      - IERC721Full
-      - ERC721Full
-      - IERC721Receiver
-  - title: Extensions
-    contracts:
-      - ERC721Mintable
-      - ERC721MetadataMintable
-      - ERC721Burnable
-      - ERC721Pausable
-  - title: Convenience
-    contracts:
-      - ERC721Holder
----
-
-This set of interfaces, contracts, and utilities are all related to the [ERC721 Non-Fungible Token Standard](https://eips.ethereum.org/EIPS/eip-721).
-
-*For a walkthrough on how to create an ERC721 token read our [ERC721 guide](../../tokens.md#erc721).*
-
-The EIP consists of three interfaces, found here as `IERC721`, `IERC721Metadata`, and `IERC721Enumerable`. Only the first one is required in a contract to be ERC721 compliant.
-
-Each interface is implemented separately in `ERC721`, `ERC721Metadata`, and `ERC721Enumerable`. You can choose the subset of functionality you would like to support in your token by combining the
-desired subset through inheritance.
-
-The fully featured token implementing all three interfaces is prepackaged as `ERC721Full`.
-
-Additionally, `IERC721Receiver` can be used to prevent tokens from becoming forever locked in contracts. Imagine sending an in-game item to an exchange address that can't send it back!. When using `safeTransferFrom()`, the token contract checks to see that the receiver is an `IERC721Receiver`, which implies that it knows how to handle `ERC721` tokens. If you're writing a contract that needs to receive `ERC721` tokens, you'll want to include this interface.
-
-Finally, some custom extensions are also included:
-- `ERC721Mintable` — like the ERC20 version, this allows certain addresses to mint new tokens
-- `ERC721Pausable` — like the ERC20 version, this allows addresses to freeze transfers of tokens
-
-> This page is incomplete. We're working to improve it for the next release. Stay tuned!

contracts/token/ERC777/ERC777.sol

@@ -9,17 +9,17 @@ import "../../utils/Address.sol";
 import "../../introspection/IERC1820Registry.sol";
 
 /**
- * @dev Implementation of the `IERC777` interface.
+ * @dev Implementation of the {IERC777} interface.
  *
  * This implementation is agnostic to the way tokens are created. This means
- * that a supply mechanism has to be added in a derived contract using `_mint`.
+ * that a supply mechanism has to be added in a derived contract using {_mint}.
  *
  * Support for ERC20 is included in this contract, as specified by the EIP: both
  * the ERC777 and ERC20 interfaces can be safely used when interacting with it.
- * Both `IERC777.Sent` and `IERC20.Transfer` events are emitted on token
+ * Both {IERC777-Sent} and {IERC20-Transfer} events are emitted on token
  * movements.
  *
- * Additionally, the `granularity` value is hard-coded to `1`, meaning that there
+ * Additionally, the {IERC777-granularity} value is hard-coded to `1`, meaning that there
  * are no special restrictions in the amount of tokens that created, moved, or
  * destroyed. This makes integration with ERC20 applications seamless.
  */
@@ -82,21 +82,21 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.name`.
+     * @dev See {IERC777-name}.
      */
     function name() public view returns (string memory) {
         return _name;
     }
 
     /**
-     * @dev See `IERC777.symbol`.
+     * @dev See {IERC777-symbol}.
      */
     function symbol() public view returns (string memory) {
         return _symbol;
     }
 
     /**
-     * @dev See `ERC20Detailed.decimals`.
+     * @dev See {ERC20Detailed-decimals}.
      *
      * Always returns 18, as per the
      * [ERC777 EIP](https://eips.ethereum.org/EIPS/eip-777#backward-compatibility).
@@ -106,7 +106,7 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.granularity`.
+     * @dev See {IERC777-granularity}.
      *
      * This implementation always returns `1`.
      */
@@ -115,7 +115,7 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.totalSupply`.
+     * @dev See {IERC777-totalSupply}.
      */
     function totalSupply() public view returns (uint256) {
         return _totalSupply;
@@ -129,21 +129,21 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.send`.
+     * @dev See {IERC777-send}.
      *
-     * Also emits a `Transfer` event for ERC20 compatibility.
+     * Also emits a {Transfer} event for ERC20 compatibility.
      */
     function send(address recipient, uint256 amount, bytes calldata data) external {
         _send(msg.sender, msg.sender, recipient, amount, data, "", true);
     }
 
     /**
-     * @dev See `IERC20.transfer`.
+     * @dev See {IERC20-transfer}.
      *
-     * Unlike `send`, `recipient` is _not_ required to implement the `tokensReceived`
+     * Unlike `send`, `recipient` is _not_ required to implement the {IERC777Recipient}
      * interface if it is a contract.
      *
-     * Also emits a `Sent` event.
+     * Also emits a {Sent} event.
      */
     function transfer(address recipient, uint256 amount) external returns (bool) {
         require(recipient != address(0), "ERC777: transfer to the zero address");
@@ -160,16 +160,16 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.burn`.
+     * @dev See {IERC777-burn}.
      *
-     * Also emits a `Transfer` event for ERC20 compatibility.
+     * Also emits a {Transfer} event for ERC20 compatibility.
      */
     function burn(uint256 amount, bytes calldata data) external {
         _burn(msg.sender, msg.sender, amount, data, "");
     }
 
     /**
-     * @dev See `IERC777.isOperatorFor`.
+     * @dev See {IERC777-isOperatorFor}.
      */
     function isOperatorFor(
         address operator,
@@ -181,7 +181,7 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.authorizeOperator`.
+     * @dev See {IERC777-authorizeOperator}.
      */
     function authorizeOperator(address operator) external {
         require(msg.sender != operator, "ERC777: authorizing self as operator");
@@ -196,7 +196,7 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.revokeOperator`.
+     * @dev See {IERC777-revokeOperator}.
      */
     function revokeOperator(address operator) external {
         require(operator != msg.sender, "ERC777: revoking self as operator");
@@ -211,16 +211,16 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.defaultOperators`.
+     * @dev See {IERC777-defaultOperators}.
      */
     function defaultOperators() public view returns (address[] memory) {
         return _defaultOperatorsArray;
     }
 
     /**
-     * @dev See `IERC777.operatorSend`.
+     * @dev See {IERC777-operatorSend}.
      *
-     * Emits `Sent` and `Transfer` events.
+     * Emits {Sent} and {Transfer} events.
      */
     function operatorSend(
         address sender,
@@ -236,9 +236,9 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC777.operatorBurn`.
+     * @dev See {IERC777-operatorBurn}.
      *
-     * Emits `Burned` and `Transfer` events.
+     * Emits {Burned} and {Transfer} events.
      */
     function operatorBurn(address account, uint256 amount, bytes calldata data, bytes calldata operatorData) external {
         require(isOperatorFor(msg.sender, account), "ERC777: caller is not an operator for holder");
@@ -246,7 +246,7 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC20.allowance`.
+     * @dev See {IERC20-allowance}.
      *
      * Note that operator and allowance concepts are orthogonal: operators may
      * not have allowance, and accounts with allowance may not be operators
@@ -257,7 +257,7 @@ contract ERC777 is IERC777, IERC20 {
     }
 
     /**
-     * @dev See `IERC20.approve`.
+     * @dev See {IERC20-approve}.
      *
      * Note that accounts cannot have allowance issued by their operators.
      */
@@ -268,13 +268,13 @@ contract ERC777 is IERC777, IERC20 {
     }
 
    /**
-    * @dev See `IERC20.transferFrom`.
+    * @dev See {IERC20-transferFrom}.
     *
     * Note that operator and allowance concepts are orthogonal: operators cannot
     * call `transferFrom` (unless they have allowance), and accounts with
     * allowance cannot call `operatorSend` (unless they are operators).
     *
-    * Emits `Sent`, `Transfer` and `Approval` events.
+    * Emits {Sent}, {Transfer} and {Approval} events.
     */
     function transferFrom(address holder, address recipient, uint256 amount) external returns (bool) {
         require(recipient != address(0), "ERC777: transfer to the zero address");
@@ -299,14 +299,14 @@ contract ERC777 is IERC777, IERC20 {
      * If a send hook is registered for `account`, the corresponding function
      * will be called with `operator`, `data` and `operatorData`.
      *
-     * See `IERC777Sender` and `IERC777Recipient`.
+     * See {IERC777Sender} and {IERC777Recipient}.
      *
-     * Emits `Minted` and `Transfer` events.
+     * Emits {Minted} and {Transfer} events.
      *
      * Requirements
      *
      * - `account` cannot be the zero address.
-     * - if `account` is a contract, it must implement the `tokensReceived`
+     * - if `account` is a contract, it must implement the {IERC777Recipient}
      * interface.
      */
     function _mint(

contracts/token/ERC777/IERC777.sol

@@ -4,10 +4,10 @@ pragma solidity ^0.5.0;
  * @dev Interface of the ERC777Token standard as defined in the EIP.
  *
  * This contract uses the
- * [ERC1820 registry standard](https://eips.ethereum.org/EIPS/eip-1820) to let
+ * https://eips.ethereum.org/EIPS/eip-1820[ERC1820 registry standard] to let
  * token holders and recipients react to token movements by using setting implementers
- * for the associated interfaces in said registry. See `IERC1820Registry` and
- * `ERC1820Implementer`.
+ * for the associated interfaces in said registry. See {IERC1820Registry} and
+ * {ERC1820Implementer}.
  */
 interface IERC777 {
     /**
@@ -45,15 +45,15 @@ interface IERC777 {
      *
      * If send or receive hooks are registered for the caller and `recipient`,
      * the corresponding functions will be called with `data` and empty
-     * `operatorData`. See `IERC777Sender` and `IERC777Recipient`.
+     * `operatorData`. See {IERC777Sender} and {IERC777Recipient}.
      *
-     * Emits a `Sent` event.
+     * Emits a {Sent} event.
      *
      * Requirements
      *
      * - the caller must have at least `amount` tokens.
      * - `recipient` cannot be the zero address.
-     * - if `recipient` is a contract, it must implement the `tokensReceived`
+     * - if `recipient` is a contract, it must implement the {IERC777Recipient}
      * interface.
      */
     function send(address recipient, uint256 amount, bytes calldata data) external;
@@ -63,9 +63,9 @@ interface IERC777 {
      * total supply.
      *
      * If a send hook is registered for the caller, the corresponding function
-     * will be called with `data` and empty `operatorData`. See `IERC777Sender`.
+     * will be called with `data` and empty `operatorData`. See {IERC777Sender}.
      *
-     * Emits a `Burned` event.
+     * Emits a {Burned} event.
      *
      * Requirements
      *
@@ -78,16 +78,16 @@ interface IERC777 {
      * Operators can send and burn tokens on behalf of their owners. All
      * accounts are their own operator.
      *
-     * See `operatorSend` and `operatorBurn`.
+     * See {operatorSend} and {operatorBurn}.
      */
     function isOperatorFor(address operator, address tokenHolder) external view returns (bool);
 
     /**
      * @dev Make an account an operator of the caller.
      *
-     * See `isOperatorFor`.
+     * See {isOperatorFor}.
      *
-     * Emits an `AuthorizedOperator` event.
+     * Emits an {AuthorizedOperator} event.
      *
      * Requirements
      *
@@ -98,9 +98,9 @@ interface IERC777 {
     /**
      * @dev Make an account an operator of the caller.
      *
-     * See `isOperatorFor` and `defaultOperators`.
+     * See {isOperatorFor} and {defaultOperators}.
      *
-     * Emits a `RevokedOperator` event.
+     * Emits a {RevokedOperator} event.
      *
      * Requirements
      *
@@ -110,11 +110,11 @@ interface IERC777 {
 
     /**
      * @dev Returns the list of default operators. These accounts are operators
-     * for all token holders, even if `authorizeOperator` was never called on
+     * for all token holders, even if {authorizeOperator} was never called on
      * them.
      *
      * This list is immutable, but individual holders may revoke these via
-     * `revokeOperator`, in which case `isOperatorFor` will return false.
+     * {revokeOperator}, in which case {isOperatorFor} will return false.
      */
     function defaultOperators() external view returns (address[] memory);
 
@@ -124,9 +124,9 @@ interface IERC777 {
      *
      * If send or receive hooks are registered for `sender` and `recipient`,
      * the corresponding functions will be called with `data` and
-     * `operatorData`. See `IERC777Sender` and `IERC777Recipient`.
+     * `operatorData`. See {IERC777Sender} and {IERC777Recipient}.
      *
-     * Emits a `Sent` event.
+     * Emits a {Sent} event.
      *
      * Requirements
      *
@@ -134,7 +134,7 @@ interface IERC777 {
      * - `sender` must have at least `amount` tokens.
      * - the caller must be an operator for `sender`.
      * - `recipient` cannot be the zero address.
-     * - if `recipient` is a contract, it must implement the `tokensReceived`
+     * - if `recipient` is a contract, it must implement the {IERC777Recipient}
      * interface.
      */
     function operatorSend(
@@ -150,9 +150,9 @@ interface IERC777 {
      * The caller must be an operator of `account`.
      *
      * If a send hook is registered for `account`, the corresponding function
-     * will be called with `data` and `operatorData`. See `IERC777Sender`.
+     * will be called with `data` and `operatorData`. See {IERC777Sender}.
      *
-     * Emits a `Burned` event.
+     * Emits a {Burned} event.
      *
      * Requirements
      *

contracts/token/ERC777/IERC777Recipient.sol

@@ -3,21 +3,21 @@ pragma solidity ^0.5.0;
 /**
  * @dev Interface of the ERC777TokensRecipient standard as defined in the EIP.
  *
- * Accounts can be notified of `IERC777` tokens being sent to them by having a
+ * Accounts can be notified of {IERC777} tokens being sent to them by having a
  * contract implement this interface (contract holders can be their own
  * implementer) and registering it on the
- * [ERC1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+ * https://eips.ethereum.org/EIPS/eip-1820[ERC1820 global registry].
  *
- * See `IERC1820Registry` and `ERC1820Implementer`.
+ * See {IERC1820Registry} and {ERC1820Implementer}.
  */
 interface IERC777Recipient {
     /**
-     * @dev Called by an `IERC777` token contract whenever tokens are being
+     * @dev Called by an {IERC777} token contract whenever tokens are being
      * moved or created into a registered account (`to`). The type of operation
      * is conveyed by `from` being the zero address or not.
      *
      * This call occurs _after_ the token contract's state is updated, so
-     * `IERC777.balanceOf`, etc., can be used to query the post-operation state.
+     * {IERC777-balanceOf}, etc., can be used to query the post-operation state.
      *
      * This function may revert to prevent the operation from being executed.
      */

contracts/token/ERC777/IERC777Sender.sol

@@ -3,21 +3,21 @@ pragma solidity ^0.5.0;
 /**
  * @dev Interface of the ERC777TokensSender standard as defined in the EIP.
  *
- * `IERC777` Token holders can be notified of operations performed on their
+ * {IERC777} Token holders can be notified of operations performed on their
  * tokens by having a contract implement this interface (contract holders can be
  *  their own implementer) and registering it on the
- * [ERC1820 global registry](https://eips.ethereum.org/EIPS/eip-1820).
+ * https://eips.ethereum.org/EIPS/eip-1820[ERC1820 global registry].
  *
- * See `IERC1820Registry` and `ERC1820Implementer`.
+ * See {IERC1820Registry} and {ERC1820Implementer}.
  */
 interface IERC777Sender {
     /**
-     * @dev Called by an `IERC777` token contract whenever a registered holder's
+     * @dev Called by an {IERC777} token contract whenever a registered holder's
      * (`from`) tokens are about to be moved or destroyed. The type of operation
      * is conveyed by `to` being the zero address or not.
      *
      * This call occurs _before_ the token contract's state is updated, so
-     * `IERC777.balanceOf`, etc., can be used to query the pre-operation state.
+     * {IERC777-balanceOf}, etc., can be used to query the pre-operation state.
      *
      * This function may revert to prevent the operation from being executed.
      */

contracts/token/ERC777/README.adoc

+= ERC 777
+This set of interfaces and contracts are all related to the [ERC777 token standard](https://eips.ethereum.org/EIPS/eip-777).
+
+TIP: For an overview of ERC777 tokens and a walkthrough on how to create a token contract read our xref:ROOT:tokens.adoc#ERC777[ERC777 guide].
+
+The token behavior itself is implemented in the core contracts: {IERC777}, {ERC777}.
+
+Additionally there are interfaces used to develop contracts that react to token movements: {IERC777Sender}, {IERC777Recipient}.
+
+== Core
+
+{{IERC777}}
+
+{{ERC777}}
+
+== Hooks
+
+{{IERC777Sender}}
+
+{{IERC777Recipient}}

contracts/token/ERC777/README.md

----
-sections:
-  - title: Core
-    contracts:
-      - IERC777
-      - ERC777
-  - title: Hooks
-    contracts:
-      - IERC777Sender
-      - IERC777Recipient
----
-
-This set of interfaces and contracts are all related to the [ERC777 token standard](https://eips.ethereum.org/EIPS/eip-777).
-
-*For an overview of ERC777 tokens and a walkthrough on how to create a token contract read our [ERC777 guide](../../tokens#erc20).*
-
-The token behavior itself is implemented in the core contracts: `IERC777`, `ERC777`.
-
-Additionally there are interfaces used to develop contracts that react to token movements: `IERC777Sender`, `IERC777Recipient`.

contracts/utils/Address.sol

@@ -11,8 +11,9 @@ library Address {
      * execution of a contract's constructor, its address will be reported as
      * not containing a contract.
      *
-     * > It is unsafe to assume that an address for which this function returns
-     * false is an externally-owned account (EOA) and not a contract.
+     * IMPORTANT: It is unsafe to assume that an address for which this
+     * function returns false is an externally-owned account (EOA) and not a
+     * contract.
      */
     function isContract(address account) internal view returns (bool) {
         // This method relies in extcodesize, which returns 0 for contracts in

contracts/utils/README.adoc

+= Utilities
+
+Miscellaneous contracts containing utility functions, often related to working with different data types.
+
+== Contracts
+
+{{Address}}
+
+{{Arrays}}
+
+{{ReentrancyGuard}}

contracts/utils/README.md

----
-title: Utilities
-sections:
-  - title: Contracts
-    contracts:
-      - Address
-      - Arrays
-      - ReentrancyGuard
----
-
-Miscellaneous contracts containing utility functions, often related to working with different data types.

contracts/utils/ReentrancyGuard.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.5.0;
 /**
  * @dev Contract module that helps prevent reentrant calls to a function.
  *
- * Inheriting from `ReentrancyGuard` will make the `nonReentrant` modifier
+ * Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier
  * available, which can be aplied to functions to make sure there are no nested
  * (reentrant) calls to them.
  *
@@ -13,7 +13,7 @@ pragma solidity ^0.5.0;
  * points to them.
  */
 contract ReentrancyGuard {
-    /// @dev counter to allow mutex lock with only one SSTORE operation
+    // counter to allow mutex lock with only one SSTORE operation
     uint256 private _guardCounter;
 
     constructor () internal {

docs/antora.yml

+name: 'contracts'
+title: 'Contracts'
+version: '2.x'
+nav:
+  - modules/ROOT/nav.adoc
+  - modules/api/nav.adoc

docs/api-stability.md

----
-id: api-stability
-title: API Stability
----
-
-On the [OpenZeppelin 2.0 release](https://github.com/OpenZeppelin/openzeppelin-solidity/releases/tag/v2.0.0), we committed ourselves to keeping a stable API. We aim to more precisely define what we understand by _stable_ and _API_ here, so users of the library can understand these guarantees and be confident their project won't break unexpectedly.
-
-In a nutshell, the API being stable means _if your project is working today, it will continue to do so_. New contracts and features will be added in minor releases, but only in a backwards compatible way.
-
-## Versioning scheme
-We follow [SemVer](https://semver.org/), which means API breakage may occur between major releases. Read more about the [release schedule](release-schedule) to know how often this happens (not very).
-
-## Solidity functions
-While the internal implementation of functions may change, their semantics and signature will remain the same. The domain of their arguments will not be less restrictive (e.g. if transferring a value of 0 is disallowed, it will remain disallowed), nor will general state restrictions be lifted (e.g. `whenPaused` modifiers).
-
-If new functions are added to a contract, it will be in a backwards-compatible way: their usage won't be mandatory, and they won't extend functionality in ways that may foreseeable break an application (e.g. [an `internal` method may be added to make it easier to retrieve information that was already available](https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1512)).
-
-### `internal`
-This extends not only to `external` and `public` functions, but also `internal` ones: many OpenZeppelin contracts are meant to be used by inheriting them (e.g. `Pausable`, `PullPayment`, the different `Roles` contracts), and are therefore used by calling these functions. Similarly, since all OpenZeppelin state variables are `private`, they can only be accessed this way (e.g. to create new `ERC20` tokens, instead of manually modifying `totalSupply` and `balances`, `_mint` should be called).
-
-`private` functions have no guarantees on their behavior, usage, or existence.
-
-Finally, sometimes language limitations will force us to e.g. make `internal` a function that should be `private` in order to implement features the way we want to. These cases will be well documented, and the normal stability guarantees won't apply.
-
-## Libraries
-Some of our Solidity libraries use `struct`s  to handle internal data that should not be accessed directly (e.g. `Roles`). There's an [open issue](https://github.com/ethereum/solidity/issues/4637) in the Solidity repository requesting a language feature to prevent said access, but it looks like it won't be implemented any time soon. Because of this, we will use leading underscores and mark said `struct`s to make it clear to the user that its contents and layout are _not_ part of the API.
-
-## Events
-No events will be removed, and their arguments won't be changed in any way. New events may be added in later versions, and existing events may be emitted under new, reasonable circumstances (e.g. [from 2.1 on, `ERC20` also emits `Approval` on `transferFrom` calls](https://github.com/OpenZeppelin/openzeppelin-solidity/issues/707)).
-
-## Gas costs
-While attempts will generally be made to lower the gas costs of working with OpenZeppelin contracts, there are no guarantees regarding this. In particular, users should not assume gas costs will not increase when upgrading library versions.
-
-## Bugfixes
-The API stability guarantees may need to be broken in order to fix a bug, and we will do so. This decision won't be made lightly however, and all options will be explored to make the change as non-disruptive as possible. When sufficient, contracts or functions which may result in unsafe behaviour will be deprecated instead of removed (e.g. [#1543](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1543) and [#1550](https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1550)).
-
-## Solidity compiler version
-Starting on version 0.5.0, the Solidity team switched to a faster release cycle, with minor releases every few weeks (v0.5.0 was released on November 2018, and v0.5.5 on March 2019), and major, breaking-change releases every couple months (with v0.6.0 scheduled for late March 2019). Including the compiler version in OpenZeppelin's stability guarantees would therefore force the library to either stick to old compilers, or release frequent major updates simply to keep up with newer Solidity releases.
-
-Because of this, **the minimum required Solidity compiler version is not part of the stability guarantees**, and users may be required to upgrade their compiler when using newer versions of OpenZeppelin. Bugfixes will still be backported to older library releases so that all versions currently in use receive these updates.
-
-You can read more about the rationale behind this, the other options we considered and why we went down this path [here](https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1498#issuecomment-449191611).

docs/contract.hbs

+{{#linkable}}
+:{{name}}: pass:normal[xref:#{{anchor}}[`{{name}}`]]
+{{/linkable}}
+
+[[{{anchor}}]]
+== `{{name}}`
+
+{{natspec.devdoc}}
+
+{{#inheritance}}
+{{#ownModifiers}}
+- xref:#{{anchor}}[{{signature}}]
+{{/ownModifiers}}
+{{/inheritance}}
+
+{{#inheritance}}
+{{#ownFunctions}}
+- xref:#{{anchor}}[{{signature}}]
+{{/ownFunctions}}
+{{/inheritance}}
+
+{{#inheritance}}
+{{#ownEvents}}
+- xref:#{{anchor}}[{{signature}}]
+{{/ownEvents}}
+{{/inheritance}}
+
+{{#ownModifiers}}
+[[{{anchor}}]]
+=== {{name}}({{args}})
+
+{{natspec.devdoc}}
+
+{{/ownModifiers}}
+{{#ownFunctions}}
+[[{{anchor}}]]
+=== {{name}}({{args}}){{#if outputs}} → {{outputs}}{{/if}}
+
+{{natspec.devdoc}}
+
+{{/ownFunctions}}
+{{#ownEvents}}
+[[{{anchor}}]]
+=== {{name}}({{args}})
+
+{{natspec.devdoc}}
+
+{{/ownEvents}}

docs/get-started.md

----
-id: get-started
-title: Getting Started
----
-
-**OpenZeppelin is a library for secure smart contract development.** It provides implementations of standards like ERC20 and ERC721 which you can deploy as-is or extend to suit your needs, as well as Solidity components to build custom contracts and more complex decentralized systems.
-
-## Install
-
-OpenZeppelin should be installed directly into your existing node.js project with `npm install openzeppelin-solidity`. We will use [Truffle](https://truffleframework.com/truffle), an Ethereum development environment, to get started.
-
-Please install Truffle and initialize your project:
-
-```sh
-$ mkdir myproject
-$ cd myproject
-$ npm init -y
-$ npm install truffle
-$ npx truffle init
-```
-
-To install the OpenZeppelin library, run the following in your Solidity project root directory:
-
-```sh
-$ npm install openzeppelin-solidity
-```
-
-_OpenZeppelin features a stable API, which means your contracts won't break unexpectedly when upgrading to a newer minor version. You can read ṫhe details in our [API Stability](api-stability) document._
-
-## Usage
-
-Once installed, you can start using the contracts in the library by importing them:
-
-```solidity
-pragma solidity ^0.5.0;
-
-import 'openzeppelin-solidity/contracts/ownership/Ownable.sol';
-
-contract MyContract is Ownable {
-  ...
-}
-```
-
-Truffle and other Ethereum development toolkits will automatically detect the installed library, and compile the imported contracts.
-
->You should always use the installed code as-is, and neither copy-paste it from online sources, nor modify it yourself.
-
-## Next Steps
-
-Check out the the guides in the sidebar to learn about different concepts, and how to use the contracts that OpenZeppelin provides.
-
-- [Learn about Access Control](access-control)
-- [Learn about Crowdsales](crowdsales)
-- [Learn about Tokens](tokens)
-- [Learn about our Utilities](utilities)
-
-OpenZeppelin's [full API](api/token/ERC20) is also thoroughly documented, and serves as a great reference when developing your smart contract application.
-
-Additionally, you can also ask for help or follow OpenZeppelin's development in the [community forum](https://forum.zeppelin.solutions).
-
-Finally, you may want to take a look at the guides on our blog, which cover several common use cases and good practices: https://blog.zeppelin.solutions/guides/home. The following articles provide great background reading, though please note, some of the referenced tools have changed as the tooling in the ecosystem continues to rapidly evolve.
-
- * [The Hitchhiker’s Guide to Smart Contracts in Ethereum](https://blog.zeppelin.solutions/the-hitchhikers-guide-to-smart-contracts-in-ethereum-848f08001f05) will help you get an overview of the various tools available for smart contract development, and help you set up your environment
-
- * [A Gentle Introduction to Ethereum Programming, Part 1](https://blog.zeppelin.solutions/a-gentle-introduction-to-ethereum-programming-part-1-783cc7796094) provides very useful information on an introductory level, including many basic concepts from the Ethereum platform
-
- * For a more in-depth dive, you may read the guide [Designing the architecture for your Ethereum application](https://blog.zeppelin.solutions/designing-the-architecture-for-your-ethereum-application-9cec086f8317), which discusses how to better structure your application and its relationship to the real world

docs/modules/ROOT/nav.adoc

+.Overview
+* xref:index.adoc[Getting Started]
+
+.Basics
+* xref:access-control.adoc[Access Control]
+* xref:tokens.adoc[Tokens]
+* xref:crowdsales.adoc[Crowdsales]
+* xref:utilities.adoc[Utilities]
+
+.In Depth
+* xref:erc20-supply.adoc[ERC20 Supply]
+
+.FAQ
+* xref:api-stability.adoc[API Stability]
+* xref:release-schedule.adoc[Release Schedule]

docs/modules/ROOT/pages/api-stability.adoc

+= API Stability
+
+On the https://github.com/OpenZeppelin/openzeppelin-solidity/releases/tag/v2.0.0[OpenZeppelin 2.0 release], we committed ourselves to keeping a stable API. We aim to more precisely define what we understand by _stable_ and _API_ here, so users of the library can understand these guarantees and be confident their project won't break unexpectedly.
+
+In a nutshell, the API being stable means _if your project is working today, it will continue to do so_. New contracts and features will be added in minor releases, but only in a backwards compatible way.
+
+[[versioning-scheme]]
+== Versioning scheme
+
+We follow https://semver.org/[SemVer], which means API breakage may occur between major releases. Read more about the link:release-schedule[release schedule] to know how often this happens (not very).
+
+[[solidity-functions]]
+== Solidity functions
+
+While the internal implementation of functions may change, their semantics and signature will remain the same. The domain of their arguments will not be less restrictive (e.g. if transferring a value of 0 is disallowed, it will remain disallowed), nor will general state restrictions be lifted (e.g. `whenPaused` modifiers).
+
+If new functions are added to a contract, it will be in a backwards-compatible way: their usage won't be mandatory, and they won't extend functionality in ways that may foreseeable break an application (e.g. https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1512[an `internal` method may be added to make it easier to retrieve information that was already available]).
+
+[[internal]]
+=== `internal`
+
+This extends not only to `external` and `public` functions, but also `internal` ones: many OpenZeppelin contracts are meant to be used by inheriting them (e.g. `Pausable`, `PullPayment`, the different `Roles` contracts), and are therefore used by calling these functions. Similarly, since all OpenZeppelin state variables are `private`, they can only be accessed this way (e.g. to create new `ERC20` tokens, instead of manually modifying `totalSupply` and `balances`, `_mint` should be called).
+
+`private` functions have no guarantees on their behavior, usage, or existence.
+
+Finally, sometimes language limitations will force us to e.g. make `internal` a function that should be `private` in order to implement features the way we want to. These cases will be well documented, and the normal stability guarantees won't apply.
+
+[[libraries]]
+== Libraries
+
+Some of our Solidity libraries use `struct`s to handle internal data that should not be accessed directly (e.g. `Roles`). There's an https://github.com/ethereum/solidity/issues/4637[open issue] in the Solidity repository requesting a language feature to prevent said access, but it looks like it won't be implemented any time soon. Because of this, we will use leading underscores and mark said `struct`s to make it clear to the user that its contents and layout are _not_ part of the API.
+
+[[events]]
+== Events
+
+No events will be removed, and their arguments won't be changed in any way. New events may be added in later versions, and existing events may be emitted under new, reasonable circumstances (e.g. https://github.com/OpenZeppelin/openzeppelin-solidity/issues/707[from 2.1 on, `ERC20` also emits `Approval` on `transferFrom` calls]).
+
+[[gas-costs]]
+== Gas costs
+
+While attempts will generally be made to lower the gas costs of working with OpenZeppelin contracts, there are no guarantees regarding this. In particular, users should not assume gas costs will not increase when upgrading library versions.
+
+[[bugfixes]]
+== Bugfixes
+
+The API stability guarantees may need to be broken in order to fix a bug, and we will do so. This decision won't be made lightly however, and all options will be explored to make the change as non-disruptive as possible. When sufficient, contracts or functions which may result in unsafe behaviour will be deprecated instead of removed (e.g. https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1543[#1543] and https://github.com/OpenZeppelin/openzeppelin-solidity/pull/1550[#1550]).
+
+[[solidity-compiler-version]]
+== Solidity compiler version
+
+Starting on version 0.5.0, the Solidity team switched to a faster release cycle, with minor releases every few weeks (v0.5.0 was released on November 2018, and v0.5.5 on March 2019), and major, breaking-change releases every couple months (with v0.6.0 scheduled for late March 2019). Including the compiler version in OpenZeppelin's stability guarantees would therefore force the library to either stick to old compilers, or release frequent major updates simply to keep up with newer Solidity releases.
+
+Because of this, *the minimum required Solidity compiler version is not part of the stability guarantees*, and users may be required to upgrade their compiler when using newer versions of OpenZeppelin. Bugfixes will still be backported to older library releases so that all versions currently in use receive these updates.
+
+You can read more about the rationale behind this, the other options we considered and why we went down this path https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1498#issuecomment-449191611[here].

docs/erc20-supply.md → docs/modules/ROOT/pages/erc20-supply.adoc

----
-id: erc20-supply
-title: Creating ERC20 Supply
----
+= Creating ERC20 Supply
 
 In this guide you will learn how to create an ERC20 token with a custom supply mechanism. We will showcase two idiomatic ways to use OpenZeppelin for this purpose that you will be able to apply to your smart contract development practice.
 
-***
+'''''
 
-The standard interface implemented by tokens built on Ethereum is called ERC20, and OpenZeppelin includes a widely used implementation of it: the aptly named [`ERC20`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/v2.1.2/contracts/token/ERC20/ERC20.sol) contract. This contract, like the standard itself, is quite simple and bare-bones. In fact, if you try deploy an instance of `ERC20` as-is it will be quite literally useless... it will have no supply! What use is a token with no supply?
+The standard interface implemented by tokens built on Ethereum is called ERC20, and OpenZeppelin includes a widely used implementation of it: the aptly named https://github.com/OpenZeppelin/openzeppelin-solidity/blob/v2.1.2/contracts/token/ERC20/ERC20.sol[`ERC20`] contract. This contract, like the standard itself, is quite simple and bare-bones. In fact, if you try deploy an instance of `ERC20` as-is it will be quite literally useless... it will have no supply! What use is a token with no supply?
 
 The way that supply is created is not defined in the ERC20 document. Every token is free to experiment with their own mechanisms, ranging from the most decentralized to the most centralized, from the most naive to the most researched, and more.
 
-#### Fixed supply
+[[fixed-supply]]
+== Fixed supply
 
 Let's say we want a token with a fixed supply of 1000, initially allocated to the account that deploys the contract. If you've used OpenZeppelin v1, you may have written code like the following.
 
-```solidity
+[source,solidity]
+----
 contract ERC20FixedSupply is ERC20 {
     constructor() public {
         totalSupply += 1000;
         balances[msg.sender] += 1000;
     }
 }
-```
+----
 
 Starting with OpenZeppelin v2 this pattern is not only discouraged, but disallowed. The variables `totalSupply` and `balances` are now private implementation details of `ERC20`, and you can't directly write to them. Instead, there is an internal `_mint` function that will do exactly this.
 
-```solidity
+[source,solidity]
+----
 contract ERC20FixedSupply is ERC20 {
     constructor() public {
         _mint(msg.sender, 1000);
     }
 }
-```
+----
 
 Encapsulating state like this makes it safer to extend contracts. For instance, in the first example we had to manually keep the `totalSupply` in sync with the modified balances, which is easy to forget. In fact, I omitted something else that is also easily forgotten: the `Transfer` event that is required by the standard, and which is relied on by some clients. The second example does not have this bug, because the internal `_mint` function takes care of it.
 
-#### Rewarding miners
+[[rewarding-miners]]
+== Rewarding miners
 
 The internal `_mint` function is the key building block that allows us to write ERC20 extensions that implement a supply mechanism.
 
 The mechanism we will implement is a token reward for the miners that produce Ethereum blocks. In Solidity we can access the address of the current block's miner in the global variable `block.coinbase`. We will mint a token reward to this address whenever someone calls the function `mintMinerReward()` on our token. The mechanism may sound silly, but you never know what kind of dynamic this might result in, and it's worth analyzing and experimenting with!
 
-```solidity
+[source,solidity]
+----
 contract ERC20WithMinerReward is ERC20 {
     function mintMinerReward() public {
         _mint(block.coinbase, 1000);
     }
 }
-```
+----
 
 As we can see, `_mint` makes it super easy to do this correctly.
 
-#### Modularizing the mechanism
+[[modularizing-the-mechanism]]
+== Modularizing the mechanism
 
-There is one supply mechanism already included in OpenZeppelin: [`ERC20Mintable`](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/v2.1.2/contracts/token/ERC20/ERC20Mintable.sol). This is a generic mechanism in which a set of accounts is assigned the `minter` role, granting them the permission to call a `mint` function, an external version of `_mint`.
+There is one supply mechanism already included in OpenZeppelin: https://github.com/OpenZeppelin/openzeppelin-solidity/blob/v2.1.2/contracts/token/ERC20/ERC20Mintable.sol[`ERC20Mintable`]. This is a generic mechanism in which a set of accounts is assigned the `minter` role, granting them the permission to call a `mint` function, an external version of `_mint`.
 
-This can be used for centralized minting, where an externally owned account (i.e. someone with a pair of cryptographic keys) decides how much supply to create and to whom. There are very legitimate use cases for this mechanism, such as [traditional asset-backed stablecoins](https://medium.com/reserve-currency/why-another-stablecoin-866f774afede#3aea).
+This can be used for centralized minting, where an externally owned account (i.e. someone with a pair of cryptographic keys) decides how much supply to create and to whom. There are very legitimate use cases for this mechanism, such as https://medium.com/reserve-currency/why-another-stablecoin-866f774afede#3aea[traditional asset-backed stablecoins].
 
 The accounts with the minter role don't need to be externally owned, though, and can just as well be smart contracts that implement a trustless mechanism. We can in fact implement the same behavior as the previous section.
 
-```solidity
+[source,solidity]
+----
 contract MinerRewardMinter {
     ERC20Mintable _token;
 
@@ -72,17 +76,19 @@ contract MinerRewardMinter {
         _token.mint(block.coinbase, 1000);
     }
 }
-```
+----
 
 This contract, when initialized with an `ERC20Mintable` instance, will result in exactly the same behavior implemented in the previous section. What is interesting about using `ERC20Mintable` is that we can easily combine multiple supply mechanisms by assigning the role to multiple contracts, and moreover that we can do this dynamically.
 
-#### Automating the reward
+[[automating-the-reward]]
+== Automating the reward
 
 Additionally to `_mint`, `ERC20` provides other internal functions that can be used or extended, such as `_transfer`. This function implements token transfers and is used by `ERC20`, so it can be used to trigger functionality automatically. This is something that can't be done with the `ERC20Mintable` approach.
 
 Adding to our previous supply mechanism, we can use this to mint a miner reward for every token transfer that is included in the blockchain.
 
-```solidity
+[source,solidity]
+----
 contract ERC20WithAutoMinerReward is ERC20 {
     function _mintMinerReward() internal {
         _mint(block.coinbase, 1000);
@@ -93,10 +99,11 @@ contract ERC20WithAutoMinerReward is ERC20 {
         super._transfer(from, to, value);
     }
 }
-```
+----
 
 Note how we override `_transfer` to first mint the miner reward and then run the original implementation by calling `super._transfer`. This last step is very important to preserve the original semantics of ERC20 transfers.
 
-#### Wrapping up
+[[wrapping-up]]
+== Wrapping up
 
 We've seen two ways to implement ERC20 supply mechanisms: internally through `_mint`, and externally through `ERC20Mintable`. Hopefully this has helped you understand how to use OpenZeppelin and some of the design principles behind it, and you can apply them to your own smart contracts.

docs/modules/ROOT/pages/index.adoc

+= Getting Started
+
+*OpenZeppelin is a library for secure smart contract development.* It provides implementations of standards like ERC20 and ERC721 which you can deploy as-is or extend to suit your needs, as well as Solidity components to build custom contracts and more complex decentralized systems.
+
+[[install]]
+== Install
+
+OpenZeppelin should be installed directly into your existing node.js project with `npm install openzeppelin-solidity`. We will use https://truffleframework.com/truffle[Truffle], an Ethereum development environment, to get started.
+
+Please install Truffle and initialize your project:
+
+[source,sh]
+----
+$ mkdir myproject
+$ cd myproject
+$ npm init -y
+$ npm install truffle
+$ npx truffle init
+----
+
+To install the OpenZeppelin library, run the following in your Solidity project root directory:
+
+[source,sh]
+----
+$ npm install openzeppelin-solidity
+----
+
+_OpenZeppelin features a stable API, which means your contracts won't break unexpectedly when upgrading to a newer minor version. You can read ṫhe details in our link:api-stability[API Stability] document._
+
+[[usage]]
+== Usage
+
+Once installed, you can start using the contracts in the library by importing them:
+
+[source,solidity]
+----
+pragma solidity ^0.5.0;
+
+import 'openzeppelin-solidity/contracts/ownership/Ownable.sol';
+
+contract MyContract is Ownable {
+  ...
+}
+----
+
+Truffle and other Ethereum development toolkits will automatically detect the installed library, and compile the imported contracts.
+
+______________________________________________________________________________________________________________________
+You should always use the installed code as-is, and neither copy-paste it from online sources, nor modify it yourself.
+______________________________________________________________________________________________________________________
+
+[[next-steps]]
+== Next Steps
+
+Check out the the guides in the sidebar to learn about different concepts, and how to use the contracts that OpenZeppelin provides.
+
+* link:access-control[Learn about Access Control]
+* link:crowdsales[Learn about Crowdsales]
+* link:tokens[Learn about Tokens]
+* link:utilities[Learn about our Utilities]
+
+OpenZeppelin's link:api/token/ERC20[full API] is also thoroughly documented, and serves as a great reference when developing your smart contract application.
+
+Additionally, you can also ask for help or follow OpenZeppelin's development in the https://forum.zeppelin.solutions[community forum].
+
+Finally, you may want to take a look at the guides on our blog, which cover several common use cases and good practices: https://blog.zeppelin.solutions/guides/home. The following articles provide great background reading, though please note, some of the referenced tools have changed as the tooling in the ecosystem continues to rapidly evolve.
+
+* https://blog.zeppelin.solutions/the-hitchhikers-guide-to-smart-contracts-in-ethereum-848f08001f05[The Hitchhiker’s Guide to Smart Contracts in Ethereum] will help you get an overview of the various tools available for smart contract development, and help you set up your environment
+* https://blog.zeppelin.solutions/a-gentle-introduction-to-ethereum-programming-part-1-783cc7796094[A Gentle Introduction to Ethereum Programming, Part 1] provides very useful information on an introductory level, including many basic concepts from the Ethereum platform
+* For a more in-depth dive, you may read the guide https://blog.zeppelin.solutions/designing-the-architecture-for-your-ethereum-application-9cec086f8317[Designing the architecture for your Ethereum application], which discusses how to better structure your application and its relationship to the real world

docs/modules/ROOT/pages/release-schedule.adoc

+= Release Schedule
+
+OpenZeppelin follows a link:api-stability[semantic versioning scheme].
+
+[[minor-releases]]
+== Minor releases
+
+OpenZeppelin has a *5 week release cycle*. This means that every five weeks a new release is published.
+
+At the beginning of the release cycle we decide which issues we want to prioritize, and assign them to https://github.com/OpenZeppelin/openzeppelin-solidity/milestones[a milestone on GitHub]. During the next five weeks, they are worked on and fixed.
+
+Once the milestone is complete, we publish a feature-frozen release candidate. The purpose of the release candidate is to have a period where the community can review the new code before the actual release. If important problems are discovered, several more release candidates may be required. After a week of no more changes to the release candidate, the new version is published.
+
+[[major-releases]]
+== Major releases
+
+Every several months a new major release may come out. These are not scheduled, but will be based on the need to release breaking changes such as a redesign of a core feature of the library (e.g. https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1146[roles] in 2.0). Since we value stability, we aim for these to happen infrequently (expect no less than six months between majors). However, we may be forced to release one when there are big changes to the Solidity language.

docs/modules/ROOT/pages/utilities.adoc

+= Utilities
+
+OpenZeppelin provides a ton of useful utilities that you can use in your project. Here are some of the more popular ones:
+
+[[cryptography]]
+== Cryptography
+
+* link:api/cryptography#ecdsa[`ECDSA`] — provides functions for recovering and managing Ethereum account ECDSA signatures:
+* to use it, declare: `using ECDSA for bytes32;`
+* signatures are tightly packed, 65 byte `bytes` that look like `{v (1)} {r (32)} {s (32)}`
+** this is the default from `web3.eth.sign` so you probably don't need to worry about this format
+* recover the signer using link:api/cryptography#ECDSA.recover(bytes32,bytes)[`myDataHash.recover(signature)`]
+* if you are using `eth_personalSign`, the signer will hash your data and then add the prefix `\x19Ethereum Signed Message:\n`, so if you're attempting to recover the signer of an Ethereum signed message hash, you'll want to use link:api/cryptography#ECDSA.toEthSignedMessageHash(bytes32)[`toEthSignedMessageHash`]
+
+Use these functions in combination to verify that a user has signed some information on-chain:
+
+[source,solidity]
+----
+keccack256(
+    abi.encodePacked(
+        someData,
+        moreData
+    )
+)
+.toEthSignedMessageHash()
+.recover(signature)
+----
+
+* link:api/cryptography#merkleproof[`MerkleProof`] — provides link:api/cryptography#MerkleProof.verify(bytes32%5B%5D,bytes32,bytes32)[`verify`] for verifying merkle proofs.
+
+[[introspection]]
+== Introspection
+
+In Solidity, it's frequently helpful to know whether or not a contract supports an interface you'd like to use. ERC165 is a standard that helps do runtime interface detection. OpenZeppelin provides some helpers, both for implementing ERC165 in your contracts and querying other contracts:
+
+* link:api/introspection#ierc165[`IERC165`] — this is the ERC165 interface that defines link:api/introspection#IERC165.supportsInterface(bytes4)[`supportsInterface`]. When implementing ERC165, you'll conform to this interface.
+* link:api/introspection#erc165[`ERC165`] — inherit this contract if you'd like to support interface detection using a lookup table in contract storage. You can register interfaces using link:api/introspection#ERC165._registerInterface(bytes4)[`_registerInterface(bytes4)`]: check out example usage as part of the ERC721 implementation.
+* link:api/introspection#erc165checker[`ERC165Checker`] — ERC165Checker simplifies the process of checking whether or not a contract supports an interface you care about.
+* include with `using ERC165Checker for address;`
+* link:api/introspection#ERC165Checker._supportsInterface(address,bytes4)[`myAddress._supportsInterface(bytes4)`]
+* link:api/introspection#ERC165Checker._supportsAllInterfaces(address,bytes4%5B%5D)[`myAddress._supportsAllInterfaces(bytes4[])`]
+
+[source,solidity]
+----
+contract MyContract {
+    using ERC165Checker for address;
+
+    bytes4 private InterfaceId_ERC721 = 0x80ac58cd;
+
+    /**
+     * @dev transfer an ERC721 token from this contract to someone else
+     */
+    function transferERC721(
+        address token,
+        address to,
+        uint256 tokenId
+    )
+        public
+    {
+        require(token.supportsInterface(InterfaceId_ERC721), "IS_NOT_721_TOKEN");
+        IERC721(token).transferFrom(address(this), to, tokenId);
+    }
+}
+----
+
+[[math]]
+== Math
+
+The most popular math related library OpenZeppelin provides is link:api/math#safemath[`SafeMath`], which provides mathematical functions that protect your contract from overflows and underflows.
+
+Include the contract with `using SafeMath for uint256;` and then call the functions:
+
+* `myNumber.add(otherNumber)`
+* `myNumber.sub(otherNumber)`
+* `myNumber.div(otherNumber)`
+* `myNumber.mul(otherNumber)`
+* `myNumber.mod(otherNumber)`
+
+Easy!
+
+[[payment]]
+== Payment
+
+Want to split some payments between multiple people? Maybe you have an app that sends 30% of art purchases to the original creator and 70% of the profits to the current owner; you can build that with link:api/payment#paymentsplitter[`PaymentSplitter`]!
+
+In solidity, there are some security concerns with blindly sending money to accounts, since it allows them to execute arbitrary code. You can read up on these security concerns in the https://consensys.github.io/smart-contract-best-practices/[Ethereum Smart Contract Best Practices] website. One of the ways to fix reentrancy and stalling problems is, instead of immediately sending Ether to accounts that need it, you can use link:api/payment#pullpayment[`PullPayment`], which offers an link:api/payment#PullPayment._asyncTransfer(address,uint256)[`_asyncTransfer`] function for sending money to something and requesting that they link:api/payment#PullPayment.withdrawPayments(address%20payable)[`withdrawPayments()`] it later.
+
+If you want to Escrow some funds, check out link:api/payment#escrow[`Escrow`] and link:api/payment#conditionalescrow[`ConditionalEscrow`] for governing the release of some escrowed Ether.
+
+[[misc]]
+=== Misc
+
+Want to check if an address is a contract? Use link:api/utils#address[`Address`] and link:api/utils#Address.isContract(address)[`Address.isContract()`].
+
+Want to keep track of some numbers that increment by 1 every time you want another one? Check out link:api/drafts#counter[`Counter`]. This is especially useful for creating incremental ERC721 `tokenId`s like we did in the last section.

docs/prelude.hbs

+{{#links}}
+:{{slug target.fullName}}: pass:normal[xref:{{path}}#{{target.anchor}}[`{{target.fullName}}`]]
+{{/links}}

docs/release-schedule.md

----
-id: release-schedule
-title:  Release Schedule
----
-
-OpenZeppelin follows a [semantic versioning scheme](api-stability).
-
-#### Minor releases
-
-OpenZeppelin has a **5 week release cycle**. This means that every five weeks a new release is published.
-
-At the beginning of the release cycle we decide which issues we want to prioritize, and assign them to [a milestone on GitHub](https://github.com/OpenZeppelin/openzeppelin-solidity/milestones). During the next five weeks, they are worked on and fixed.
-
-Once the milestone is complete, we publish a feature-frozen release candidate. The purpose of the release candidate is to have a period where the community can review the new code before the actual release. If important problems are discovered, several more release candidates may be required. After a week of no more changes to the release candidate, the new version is published.
-
-#### Major releases
-
-Every several months a new major release may come out. These are not scheduled, but will be based on the need to release breaking changes such as a redesign of a core feature of the library (e.g. [roles](https://github.com/OpenZeppelin/openzeppelin-solidity/issues/1146) in 2.0). Since we value stability, we aim for these to happen infrequently (expect no less than six months between majors). However, we may be forced to release one when there are big changes to the Solidity language.

docs/sidebar.json

-{
-  "Overview": [
-    "get-started"
-  ],
-  "Basics": [
-    "access-control",
-    "crowdsales",
-    "tokens",
-    "utilities"
-  ],
-  "In Depth": [
-    "erc20-supply"
-  ],
-  "API Reference": [
-    {
-      "type": "directory",
-      "directory": "api"
-    }
-  ],
-  "FAQ": [
-    "api-stability",
-    "release-schedule"
-  ]
-}

docs/utilities.md

----
-id: utilities
-title: Utilities
----
-
-OpenZeppelin provides a ton of useful utilities that you can use in your project. Here are some of the more popular ones:
-
-## Cryptography
-
-- [`ECDSA`](api/cryptography#ecdsa) — provides functions for recovering and managing Ethereum account ECDSA signatures:
-  - to use it, declare: `using ECDSA for bytes32;`
-  - signatures are tightly packed, 65 byte `bytes` that look like `{v (1)} {r (32)} {s (32)}`
-    - this is the default from `web3.eth.sign` so you probably don't need to worry about this format
-  - recover the signer using [`myDataHash.recover(signature)`](api/cryptography#ECDSA.recover(bytes32,bytes))
-  - if you are using `eth_personalSign`, the signer will hash your data and then add the prefix `\x19Ethereum Signed Message:\n`, so if you're attempting to recover the signer of an Ethereum signed message hash, you'll want to use [`toEthSignedMessageHash`](api/cryptography#ECDSA.toEthSignedMessageHash(bytes32))
-
-
-Use these functions in combination to verify that a user has signed some information on-chain:
-
-```solidity
-keccack256(
-    abi.encodePacked(
-        someData,
-        moreData
-    )
-)
-.toEthSignedMessageHash()
-.recover(signature)
-```
-
-- [`MerkleProof`](api/cryptography#merkleproof) — provides [`verify`](api/cryptography#MerkleProof.verify(bytes32[],bytes32,bytes32)) for verifying merkle proofs.
-
-
-## Introspection
-
-In Solidity, it's frequently helpful to know whether or not a contract supports an interface you'd like to use. ERC165 is a standard that helps do runtime interface detection. OpenZeppelin provides some helpers, both for implementing ERC165 in your contracts and querying other contracts:
-
-- [`IERC165`](api/introspection#ierc165) — this is the ERC165 interface that defines [`supportsInterface`](api/introspection#IERC165.supportsInterface(bytes4)). When implementing ERC165, you'll conform to this interface.
-- [`ERC165`](api/introspection#erc165) — inherit this contract if you'd like to support interface detection using a lookup table in contract storage. You can register interfaces using [`_registerInterface(bytes4)`](api/introspection#ERC165._registerInterface(bytes4)): check out example usage as part of the ERC721 implementation.
-- [`ERC165Checker`](api/introspection#erc165checker) — ERC165Checker simplifies the process of checking whether or not a contract supports an interface you care about.
-  - include with `using ERC165Checker for address;`
-  - [`myAddress._supportsInterface(bytes4)`](api/introspection#ERC165Checker._supportsInterface(address,bytes4))
-  - [`myAddress._supportsAllInterfaces(bytes4[])`](api/introspection#ERC165Checker._supportsAllInterfaces(address,bytes4[]))
-
-
-```solidity
-contract MyContract {
-    using ERC165Checker for address;
-
-    bytes4 private InterfaceId_ERC721 = 0x80ac58cd;
-
-    /**
-     * @dev transfer an ERC721 token from this contract to someone else
-     */
-    function transferERC721(
-        address token,
-        address to,
-        uint256 tokenId
-    )
-        public
-    {
-        require(token.supportsInterface(InterfaceId_ERC721), "IS_NOT_721_TOKEN");
-        IERC721(token).transferFrom(address(this), to, tokenId);
-    }
-}
-```
-
-## Math
-
-The most popular math related library OpenZeppelin provides is [`SafeMath`](api/math#safemath), which provides mathematical functions that protect your contract from overflows and underflows.
-
-Include the contract with `using SafeMath for uint256;` and then call the functions:
-
-- `myNumber.add(otherNumber)`
-- `myNumber.sub(otherNumber)`
-- `myNumber.div(otherNumber)`
-- `myNumber.mul(otherNumber)`
-- `myNumber.mod(otherNumber)`
-
-Easy!
-
-## Payment
-
-Want to split some payments between multiple people? Maybe you have an app that sends 30% of art purchases to the original creator and 70% of the profits to the current owner; you can build that with [`PaymentSplitter`](api/payment#paymentsplitter)!
-
-In solidity, there are some security concerns with blindly sending money to accounts, since it allows them to execute arbitrary code. You can read up on these security concerns in the [Ethereum Smart Contract Best Practices](https://consensys.github.io/smart-contract-best-practices/) website. One of the ways to fix reentrancy and stalling problems is, instead of immediately sending Ether to accounts that need it, you can use [`PullPayment`](api/payment#pullpayment), which offers an [`_asyncTransfer`](api/payment#PullPayment._asyncTransfer(address,uint256)) function for sending money to something and requesting that they [`withdrawPayments()`](api/payment#PullPayment.withdrawPayments(address%20payable)) it later.
-
-If you want to Escrow some funds, check out [`Escrow`](api/payment#escrow) and [`ConditionalEscrow`](api/payment#conditionalescrow) for governing the release of some escrowed Ether.
-
-### Misc
-
-Want to check if an address is a contract? Use [`Address`](api/utils#address) and [`Address.isContract()`](api/utils#Address.isContract(address)).
-
-Want to keep track of some numbers that increment by 1 every time you want another one? Check out [`Counter`](api/drafts#counter). This is especially useful for creating incremental ERC721 `tokenId`s like we did in the last section.

package.json

@@ -14,7 +14,7 @@
     "console": "truffle console",
     "coverage": "scripts/coverage.sh",
     "docsite": "scripts/docsite.sh",
-    "docgen": "scripts/docgen.sh",
+    "prepare-docs": "scripts/prepare-docs.sh",
     "lint": "npm run lint:js && npm run lint:sol",
     "lint:fix": "npm run lint:js:fix",
     "lint:js": "eslint .",
@@ -59,11 +59,10 @@
     "ganache-cli-coverage": "https://github.com/frangio/ganache-cli/releases/download/v6.4.1-coverage/ganache-cli-coverage-6.4.1.tgz",
     "micromatch": "^4.0.2",
     "nodemon": "^1.19.0",
-    "openzeppelin-docsite": "github:OpenZeppelin/openzeppelin-docsite#ee1df82d52ad3df4337b20392627975091f8d5b3",
     "openzeppelin-test-helpers": "^0.4",
     "solhint": "2.1.0",
     "solidity-coverage": "github:rotcivegaf/solidity-coverage#5875f5b7bc74d447f3312c9c0e9fc7814b482477",
-    "solidity-docgen": "github:OpenZeppelin/solidity-docgen#03f42b5e271b1e1c1d0b814b921ecdc086055255",
+    "solidity-docgen": "^0.3.0-beta.2",
     "truffle": "^5.0.18"
   }
 }

scripts/docgen.sh

-#!/usr/bin/env bash
-
-OUTDIR=docs/api
-
-rm -rf "$OUTDIR"
-solidity-docgen -o "$OUTDIR" -i contracts/mocks -i contracts/examples

scripts/docsite.sh

 #!/usr/bin/env bash
 
-# usage: npm run docsite [build|start]
+# usage: npm run docsite
 
 set -o errexit
 
-npm run docgen
-
-if [ "$1" = start ]; then
-  npx concurrently -n docgen,docsite --no-color \
-    'nodemon -C -w contracts -e sol,md -x npm run docgen' \
-    'openzeppelin-docsite-run start'
-else
-  npx openzeppelin-docsite-run "$1"
+if [ ! -d openzeppelin-docs ]; then
+  git clone https://github.com/frangio/openzeppelin-docs.git
 fi
+
+git -C openzeppelin-docs pull
+
+npx concurrently \
+  'nodemon --delay 1 -e "*" -w contracts -w "docs/*.hbs" -x npm run prepare-docs' \
+  'cd docs; env DISABLE_PREPARE_DOCS= nodemon --delay 1 -e adoc,yml ../openzeppelin-docs/build-local.js' \
+  'http-server -c-1 openzeppelin-docs/build/site'

scripts/prepare-docs.sh

+#!/usr/bin/env bash
+
+OUTDIR=docs/modules/api/pages/
+
+rm -rf "$OUTDIR"
+solidity-docgen -t docs -o "$OUTDIR" -e contracts/mocks,contracts/examples
+
+gen-nav() {
+  echo '.API'
+  find "$OUTDIR" -type f | sed -Ee "s:$OUTDIR(.+):* xref\:\1[]:"
+}
+
+gen-nav > "$OUTDIR/../nav.adoc"