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

@@ -0,0 +1,21 @@
+= 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

@@ -1,9 +0,0 @@
----
-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

@@ -0,0 +1,35 @@
+= 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

@@ -1,13 +0,0 @@
----
-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.md → contracts/cryptography/README.adoc

@@ -1,9 +1,9 @@
----
-sections:
-  - title: Libraries
-    contracts:
-      - ECDSA
-      - MerkleProof
----
+= Cryptography
 
 This collection of libraries provides simple and safe ways to use different cryptographic primitives.
+
+== Libraries
+
+{{ECDSA}}
+
+{{MerkleProof}}

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

@@ -0,0 +1,23 @@
+= 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

@@ -1,16 +0,0 @@
----
-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

@@ -1,7 +1,7 @@
 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

@@ -1,16 +1,4 @@
----
-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

@@ -0,0 +1,9 @@
+= Math
+
+These are math-related utilities.
+
+== Libraries
+
+{{SafeMath}}
+
+{{Math}}

contracts/math/README.md

@@ -1,10 +0,0 @@
----
-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

@@ -0,0 +1,9 @@
+= 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

@@ -1,3 +0,0 @@
-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

@@ -0,0 +1,17 @@
+= 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

@@ -1,10 +0,0 @@
----
-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

@@ -1,8 +0,0 @@
----
-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

@@ -0,0 +1,47 @@
+= 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

@@ -1,38 +0,0 @@
----
-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

@@ -24,13 +24,13 @@ contract IERC721 is IERC165 {
      * @dev Transfers a specific NFT (`tokenId`) from one account (`from`) to
      * another (`to`).
      *
-     * 
+     *
      *
      * Requirements:
      * - `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

@@ -0,0 +1,54 @@
+= 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

@@ -1,42 +0,0 @@
----
-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

@@ -0,0 +1,20 @@
+= 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

@@ -1,19 +0,0 @@
----
-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

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

contracts/utils/README.md

@@ -1,11 +0,0 @@
----
-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

@@ -0,0 +1,6 @@
+name: 'contracts'
+title: 'Contracts'
+version: '2.x'
+nav:
+  - modules/ROOT/nav.adoc
+  - modules/api/nav.adoc

docs/contract.hbs

@@ -0,0 +1,48 @@
+{{#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

@@ -1,67 +0,0 @@
----
-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

@@ -0,0 +1,15 @@
+.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/access-control.md → docs/modules/ROOT/pages/access-control.adoc

@@ -1,16 +1,16 @@
----
-id: access-control
-title: Access Control
----
-Access control—that is, "who is allowed to do this thing"—is incredibly important in the world of smart contracts. The access control of your contract may govern who can mint tokens, vote on proposals, freeze transfers, and many others. It is therefore critical to understand how you implement it, lest someone else [steals your whole system](https://blog.zeppelin.solutions/on-the-parity-wallet-multisig-hack-405a8c12e8f7).
+= Access Control
 
-## Ownership and `Ownable`
+Access control—that is, "who is allowed to do this thing"—is incredibly important in the world of smart contracts. The access control of your contract may govern who can mint tokens, vote on proposals, freeze transfers, and many others. It is therefore critical to understand how you implement it, lest someone else https://blog.zeppelin.solutions/on-the-parity-wallet-multisig-hack-405a8c12e8f7[steals your whole system].
+
+[[ownership-and-ownable]]
+== Ownership and `Ownable`
 
 The most common and basic form of access control is the concept of _ownership_: there's an account that is the `owner` of a contract and can do administrative tasks on it. This approach is perfectly reasonable for contracts that have a single administrative user.
 
-OpenZeppelin provides [`Ownable`](api/ownership#ownable) for implementing ownership in your contracts.
+OpenZeppelin provides link:api/ownership#ownable[`Ownable`] for implementing ownership in your contracts.
 
-```solidity
+[source,solidity]
+----
 pragma solidity ^0.5.0;
 
 import "openzeppelin-solidity/contracts/ownership/Ownable.sol";
@@ -24,20 +24,18 @@ contract MyContract is Ownable {
         // only the owner can call specialThing()!
     }
 }
-```
+----
 
-By default, the [`owner`](api/ownership#Ownable.owner()) of an `Ownable` contract is the account that deployed it, which is usually exactly what you want.
+By default, the link:api/ownership#Ownable.owner()[`owner`] of an `Ownable` contract is the account that deployed it, which is usually exactly what you want.
 
-Ownable also lets you:
-- [`transferOwnership`](api/ownership#Ownable.transferOwnership(address)) from the owner account to a new one
-- [`renounceOwnership`](api/ownership#Ownable.renounceOwnership()) for the owner to lose this administrative privilege, a common pattern after an initial stage with centralized administration is over
-  - **⚠ Warning! ⚠** Removing the owner altogether will mean that administrative tasks that are protected by `onlyOwner` will no longer be callable!
+Ownable also lets you: - link:api/ownership#Ownable.transferOwnership(address)[`transferOwnership`] from the owner account to a new one - link:api/ownership#Ownable.renounceOwnership()[`renounceOwnership`] for the owner to lose this administrative privilege, a common pattern after an initial stage with centralized administration is over - *⚠ Warning! ⚠* Removing the owner altogether will mean that administrative tasks that are protected by `onlyOwner` will no longer be callable!
 
-Note that **a contract can also be the owner of another one**! This opens the door to using, for example, a [Gnosis Multisig](https://github.com/gnosis/MultiSigWallet) or [Gnosis Safe](https://safe.gnosis.io), an [Aragon DAO](https://aragon.org), an [ERC725/uPort](https://www.uport.me) identity contract, or a totally custom contract that _you_ create.
+Note that *a contract can also be the owner of another one*! This opens the door to using, for example, a https://github.com/gnosis/MultiSigWallet[Gnosis Multisig] or https://safe.gnosis.io[Gnosis Safe], an https://aragon.org[Aragon DAO], an https://www.uport.me[ERC725/uPort] identity contract, or a totally custom contract that _you_ create.
 
-In this way you can use _composability_ to add additional layers of access control complexity to your contracts. Instead of having a single regular Ethereum account (Externally Owned Account, or EOA) as the owner, you could use a 2-of-3 multisig run by your project leads, for example. Prominent projects in the space, such as [MakerDAO](https://makerdao.com), use systems similar to this one.
+In this way you can use _composability_ to add additional layers of access control complexity to your contracts. Instead of having a single regular Ethereum account (Externally Owned Account, or EOA) as the owner, you could use a 2-of-3 multisig run by your project leads, for example. Prominent projects in the space, such as https://makerdao.com[MakerDAO], use systems similar to this one.
 
-## Role-Based Access Control
+[[role-based-access-control]]
+== Role-Based Access Control
 
 While the simplicity of _ownership_ can be useful for simple systems or quick prototyping, different levels of authorization are often needed. An account may be able to ban users from a system, but not create new tokens. _Role-Based Access Control (RBAC)_ offers flexibility in this regard.
 
@@ -45,13 +43,15 @@ In essence, we will be defining multiple _roles_, each allowed to perform differ
 
 Most of software development uses access control systems that are role-based: some users are regular users, some may be supervisors or managers, and a few will often have administrative privileges.
 
-### Using `Roles`
+[[using-roles]]
+=== Using `Roles`
 
-OpenZeppelin provides [`Roles`](api/access#roles) for implementing role-based access control. Its usage is straightforward: for each role that you want to define, you'll store a  variable of type `Role`, which will hold the list of accounts with that role.
+OpenZeppelin provides link:api/access#roles[`Roles`] for implementing role-based access control. Its usage is straightforward: for each role that you want to define, you'll store a variable of type `Role`, which will hold the list of accounts with that role.
 
-Here's an simple example of using `Roles` in an [`ERC20` token](tokens#erc20): we'll define two roles, `namers` and `minters`, that will be able to change the name of the token contract, and mint new tokens, respectively.
+Here's an simple example of using `Roles` in an link:tokens#erc20[`ERC20` token]: we'll define two roles, `namers` and `minters`, that will be able to change the name of the token contract, and mint new tokens, respectively.
 
-```solidity
+[source,solidity]
+----
 pragma solidity ^0.5.0;
 
 import "openzeppelin-solidity/contracts/access/Roles.sol";
@@ -92,16 +92,17 @@ contract MyToken is ERC20, ERC20Detailed {
         symbol = symbol;
     }
 }
-```
+----
 
 So clean! By splitting concerns this way, we can define more granular levels of permission, which was lacking in the _ownership_ approach to access control. Note that an account may have more than one role, if desired.
 
-OpenZeppelin uses `Roles` extensively with predefined contracts that encode rules for each specific role. A few examples are: [`ERC20Mintable`](api/token/ERC20#erc20mintable) which uses the [`MinterRole`](api/access#minterrole) to determine who can mint tokens, and [`WhitelistCrowdsale`](api/crowdsale#whitelistcrowdsale) which uses both [`WhitelistAdminRole`](api/access#whitelistadminrole) and [`WhitelistedRole`](api/access#whitelistedrole) to create a set of accounts that can purchase tokens.
+OpenZeppelin uses `Roles` extensively with predefined contracts that encode rules for each specific role. A few examples are: link:api/token/ERC20#erc20mintable[`ERC20Mintable`] which uses the link:api/access#minterrole[`MinterRole`] to determine who can mint tokens, and link:api/crowdsale#whitelistcrowdsale[`WhitelistCrowdsale`] which uses both link:api/access#whitelistadminrole[`WhitelistAdminRole`] and link:api/access#whitelistedrole[`WhitelistedRole`] to create a set of accounts that can purchase tokens.
 
-This flexibility allows for interesting setups: for example, a [`MintedCrowdsale`](api/crowdsale#mintedcrowdsale) expects to be given the `MinterRole` of an `ERC20Mintable` in order to work, but the token contract could also extend [`ERC20Pausable`](api/token/ERC20#erc20pausable) and assign the [`PauserRole`](api/access#pauserrole) to a DAO that serves as a contingency mechanism in case a vulnerability is discovered in the contract code. Limiting what each component of a system is able to do is known as the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), and is a good security practice.
+This flexibility allows for interesting setups: for example, a link:api/crowdsale#mintedcrowdsale[`MintedCrowdsale`] expects to be given the `MinterRole` of an `ERC20Mintable` in order to work, but the token contract could also extend link:api/token/ERC20#erc20pausable[`ERC20Pausable`] and assign the link:api/access#pauserrole[`PauserRole`] to a DAO that serves as a contingency mechanism in case a vulnerability is discovered in the contract code. Limiting what each component of a system is able to do is known as the https://en.wikipedia.org/wiki/Principle_of_least_privilege[principle of least privilege], and is a good security practice.
 
-## Usage in OpenZeppelin
+[[usage-in-openzeppelin]]
+== Usage in OpenZeppelin
 
 You'll notice that none of the OpenZeppelin contracts use `Ownable`. `Roles` is a prefferred solution, because it provides the user of the library with enough flexibility to adapt the provided contracts to their needs.
 
-There are some cases, though, where there's a direct relationship between contracts. For example, [`RefundableCrowdsale`](api/crowdsale#refundablecrowdsale) deploys a [`RefundEscrow`](api/payment#refundescrow) on construction, to hold its funds. For those cases, we'll use [`Secondary`](api/ownership#secondary) to create a _secondary_ contract that allows a _primary_ contract to manage it. You could also think of these as _auxiliary_ contracts.
+There are some cases, though, where there's a direct relationship between contracts. For example, link:api/crowdsale#refundablecrowdsale[`RefundableCrowdsale`] deploys a link:api/payment#refundescrow[`RefundEscrow`] on construction, to hold its funds. For those cases, we'll use link:api/ownership#secondary[`Secondary`] to create a _secondary_ contract that allows a _primary_ contract to manage it. You could also think of these as _auxiliary_ contracts.

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

@@ -1,42 +1,55 @@
----
-id: api-stability
-title: API Stability
----
+= 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.
+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
-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).
+[[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
 
-## 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)).
+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`
 
-### `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.
+[[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
-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)).
+[[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
 
-## 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)).
+[[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
 
-## 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.
+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).
+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/crowdsales.md → docs/modules/ROOT/pages/crowdsales.adoc

@@ -1,43 +1,28 @@
----
-id: crowdsales
-title: Crowdsales
----
+= Crowdsales
 
 Crowdsales are a popular use for Ethereum; they let you allocate tokens to network participants in various ways, mostly in exchange for Ether. They come in a variety of shapes and flavors, so let's go over the various types available in OpenZeppelin and how to use them.
 
-Crowdsales have a bunch of different properties, but here are some important ones:
-- Price & Rate Configuration
-  - Does your crowdsale sell tokens at a fixed price?
-  - Does the price change over time or as a function of demand?
-- Emission
-  - How is this token actually sent to participants?
-- Validation — Who is allowed to purchase tokens?
-  - Are there KYC / AML checks?
-  - Is there a max cap on tokens?
-  - What if that cap is per-participant?
-  - Is there a starting and ending time frame?
-- Distribution
-  - Does distribution of funds happen in real-time or after the crowdsale?
-  - Can participants receive a refund if the goal is not met?
-
-To manage all of the different combinations and flavors of crowdsales, OpenZeppelin provides a highly configurable [`Crowdsale`](api/crowdsale#crowdsale) base contract that can be combined with various other functionalities to construct a bespoke crowdsale.
-
-## Crowdsale Rate
+Crowdsales have a bunch of different properties, but here are some important ones: - Price & Rate Configuration - Does your crowdsale sell tokens at a fixed price? - Does the price change over time or as a function of demand? - Emission - How is this token actually sent to participants? - Validation — Who is allowed to purchase tokens? - Are there KYC / AML checks? - Is there a max cap on tokens? - What if that cap is per-participant? - Is there a starting and ending time frame? - Distribution - Does distribution of funds happen in real-time or after the crowdsale? - Can participants receive a refund if the goal is not met?
+
+To manage all of the different combinations and flavors of crowdsales, OpenZeppelin provides a highly configurable link:api/crowdsale#crowdsale[`Crowdsale`] base contract that can be combined with various other functionalities to construct a bespoke crowdsale.
+
+[[crowdsale-rate]]
+== Crowdsale Rate
 
 Understanding the rate of a crowdsale is super important, and mistakes here are a common source of bugs.
 
-✨ **HOLD UP FAM THIS IS IMPORTANT** ✨
+✨ *HOLD UP FAM THIS IS IMPORTANT* ✨
 
-Firstly, **all currency math is done in the smallest unit of that currency and converted to the correct decimal places when _displaying_ the currency**.
+Firstly, *all currency math is done in the smallest unit of that currency and converted to the correct decimal places when _displaying_ the currency*.
 
 This means that when you do math in your smart contracts, you need to understand that you're adding, dividing, and multiplying the smallest amount of a currency (like wei), _not_ the commonly-used displayed value of the currency (Ether).
 
 In Ether, the smallest unit of the currency is wei, and `1 ETH === 10^18 wei`. In tokens, the process is _very similar_: `1 TKN === 10^(decimals) TKNbits`.
 
-- The smallest unit of a token is "bits" or `TKNbits`.
-- The display value of a token is `TKN`, which is `TKNbits * 10^(decimals)`
+* The smallest unit of a token is "bits" or `TKNbits`.
+* The display value of a token is `TKN`, which is `TKNbits * 10^(decimals)`
 
-What people usually call "one token" is actually a bunch of TKNbits, displayed to look like `1 TKN`. This is the same relationship that Ether and wei have. And what you're _always_ doing calculations in is **TKNbits and wei**.
+What people usually call "one token" is actually a bunch of TKNbits, displayed to look like `1 TKN`. This is the same relationship that Ether and wei have. And what you're _always_ doing calculations in is *TKNbits and wei*.
 
 So, if you want to issue someone "one token for every 2 wei" and your decimals are 18, your rate is `0.5e18`. Then, when I send you `2 wei`, your crowdsale issues me `2 * 0.5e18 TKNbits`, which is exactly equal to `10^18 TKNbits` and is displayed as `1 TKN`.
 
@@ -45,48 +30,53 @@ If you want to issue someone "`1 TKN` for every `1 ETH`", and your decimals are
 
 One more for practice: if I want to issue "1 TKN for every dollar (USD) in Ether", we would calculate it as follows:
 
-- assume 1 ETH == $400
-- therefore, 10^18 wei = $400
-- therefore, 1 USD is `10^18 / 400`, or `2.5 * 10^15 wei`
-- we have a decimals of 18, so we'll use `10 ^ 18 TKNbits` instead of `1 TKN`
-- therefore, if the participant sends the crowdsale `2.5 * 10^15 wei` we should give them `10 ^ 18 TKNbits`
-- therefore the rate is `2.5 * 10^15 wei === 10^18 TKNbits`, or `1 wei = 400 TKNbits`
-- therefore, our rate is `400`
+* assume 1 ETH == $400
+* therefore, 10^18 wei = $400
+* therefore, 1 USD is `10^18 / 400`, or `2.5 * 10^15 wei`
+* we have a decimals of 18, so we'll use `10 ^ 18 TKNbits` instead of `1 TKN`
+* therefore, if the participant sends the crowdsale `2.5 * 10^15 wei` we should give them `10 ^ 18 TKNbits`
+* therefore the rate is `2.5 * 10^15 wei === 10^18 TKNbits`, or `1 wei = 400 TKNbits`
+* therefore, our rate is `400`
 
 (this process is pretty straightforward when you keep 18 decimals, the same as Ether/wei)
 
-
-## Token Emission
+[[token-emission]]
+== Token Emission
 
 One of the first decisions you have to make is "how do I get these tokens to users?". This is usually done in one of three ways:
 
-- (default) — The `Crowdsale` contract owns tokens and simply transfers tokens from its own ownership to users that purchase them.
-- [`MintedCrowdsale`](api/crowdsale#mintedcrowdsale) — The `Crowdsale` mints tokens when a purchase is made.
-- [`AllowanceCrowdsale`](api/crowdsale#allowancecrowdsale) — The `Crowdsale` is granted an allowance to another wallet (like a Multisig) that already owns the tokens to be sold in the crowdsale.
+* (default) — The `Crowdsale` contract owns tokens and simply transfers tokens from its own ownership to users that purchase them.
+* link:api/crowdsale#mintedcrowdsale[`MintedCrowdsale`] — The `Crowdsale` mints tokens when a purchase is made.
+* link:api/crowdsale#allowancecrowdsale[`AllowanceCrowdsale`] — The `Crowdsale` is granted an allowance to another wallet (like a Multisig) that already owns the tokens to be sold in the crowdsale.
 
-### Default Emission
+[[default-emission]]
+=== Default Emission
 
 In the default scenario, your crowdsale must own the tokens that are sold. You can send the crowdsale tokens through a variety of methods, but here's what it looks like in Solidity:
 
-```solidity
+[source,solidity]
+----
 IERC20(tokenAddress).transfer(CROWDSALE_ADDRESS, SOME_TOKEN_AMOUNT);
-```
+----
 
 Then when you deploy your crowdsale, simply tell it about the token
 
-```solidity
+[source,solidity]
+----
 new Crowdsale(
     1,             // rate in TKNbits
     MY_WALLET,     // address where Ether is sent
     TOKEN_ADDRESS  // the token contract address
 );
-```
+----
 
-### Minted Crowdsale
+[[minted-crowdsale]]
+=== Minted Crowdsale
 
-To use a [`MintedCrowdsale`](api/crowdsale#mintedcrowdsale), your token must also be a [`ERC20Mintable`](api/token/ERC20#erc20mintable) token that the crowdsale has permission to mint from. This can look like:
+To use a link:api/crowdsale#mintedcrowdsale[`MintedCrowdsale`], your token must also be a link:api/token/ERC20#erc20mintable[`ERC20Mintable`] token that the crowdsale has permission to mint from. This can look like:
 
-```solidity
+[source,solidity]
+----
 contract MyToken is ERC20, ERC20Mintable {
     // ... see "Tokens" for more info
 }
@@ -124,13 +114,15 @@ contract MyCrowdsaleDeployer {
         token.renounceMinter();
     }
 }
-```
+----
 
-### AllowanceCrowdsale
+[[allowancecrowdsale]]
+=== AllowanceCrowdsale
 
-Use an [`AllowanceCrowdsale`](api/crowdsale#allowancecrowdsale) to send tokens from another wallet to the participants of the crowdsale. In order for this to work, the source wallet must give the crowdsale an allowance via the ERC20 [`approve`](api/token/ERC20#IERC20.approve(address,uint256)) method.
+Use an link:api/crowdsale#allowancecrowdsale[`AllowanceCrowdsale`] to send tokens from another wallet to the participants of the crowdsale. In order for this to work, the source wallet must give the crowdsale an allowance via the ERC20 link:api/token/ERC20#IERC20.approve(address,uint256)[`approve`] method.
 
-```solidity
+[source,solidity]
+----
 contract MyCrowdsale is Crowdsale, AllowanceCrowdsale {
     constructor(
         uint256 rate,
@@ -145,26 +137,29 @@ contract MyCrowdsale is Crowdsale, AllowanceCrowdsale {
 
     }
 }
-```
+----
 
 Then after the crowdsale is created, don't forget to approve it to use your tokens!
 
-```solidity
+[source,solidity]
+----
 IERC20(tokenAddress).approve(CROWDSALE_ADDRESS, SOME_TOKEN_AMOUNT);
-```
+----
 
-## Validation
+[[validation]]
+== Validation
 
 There are a bunch of different validation requirements that your crowdsale might be a part of:
 
-- [`CappedCrowdsale`](api/crowdsale#cappedcrowdsale) — adds a cap to your crowdsale, invalidating any purchases that would exceed that cap
-- [`IndividuallyCappedCrowdsale`](api/crowdsale#individuallycappedcrowdsale) — caps an individual's contributions.
-- [`WhitelistCrowdsale`](api/crowdsale#whitelistcrowdsale) — only allow whitelisted participants to purchase tokens. this is useful for putting your KYC / AML whitelist on-chain!
-- [`TimedCrowdsale`](api/crowdsale#timedcrowdsale) — adds an [`openingTime`](api/crowdsale#TimedCrowdsale.openingTime()) and [`closingTime`](api/crowdsale#TimedCrowdsale.closingTime()) to your crowdsale
+* link:api/crowdsale#cappedcrowdsale[`CappedCrowdsale`] — adds a cap to your crowdsale, invalidating any purchases that would exceed that cap
+* link:api/crowdsale#individuallycappedcrowdsale[`IndividuallyCappedCrowdsale`] — caps an individual's contributions.
+* link:api/crowdsale#whitelistcrowdsale[`WhitelistCrowdsale`] — only allow whitelisted participants to purchase tokens. this is useful for putting your KYC / AML whitelist on-chain!
+* link:api/crowdsale#timedcrowdsale[`TimedCrowdsale`] — adds an link:api/crowdsale#TimedCrowdsale.openingTime()[`openingTime`] and link:api/crowdsale#TimedCrowdsale.closingTime()[`closingTime`] to your crowdsale
 
 Simply mix and match these crowdsale flavors to your heart's content:
 
-```solidity
+[source,solidity]
+----
 contract MyCrowdsale is Crowdsale, CappedCrowdsale, TimedCrowdsale {
 
     constructor(
@@ -185,9 +180,10 @@ contract MyCrowdsale is Crowdsale, CappedCrowdsale, TimedCrowdsale {
         // and stops accepting contributions once it reaches `cap`
     }
 }
-```
+----
 
-## Distribution
+[[distribution]]
+== Distribution
 
 There comes a time in every crowdsale's life where it must relinquish the tokens it's been entrusted with. It's your decision as to when that happens!
 
@@ -195,11 +191,13 @@ The default behavior is to release tokens as participants purchase them, but som
 
 OpenZeppelin is here to make that easy!
 
-### PostDeliveryCrowdsale
+[[postdeliverycrowdsale]]
+=== PostDeliveryCrowdsale
 
-The [`PostDeliveryCrowdsale`](api/crowdsale#postdeliverycrowdsale), as its name implies, distributes tokens after the crowdsale has finished, letting users call [`withdrawTokens`](api/crowdsale#PostDeliveryCrowdsale.withdrawTokens(address)) in order to claim the tokens they've purchased.
+The link:api/crowdsale#postdeliverycrowdsale[`PostDeliveryCrowdsale`], as its name implies, distributes tokens after the crowdsale has finished, letting users call link:api/crowdsale#PostDeliveryCrowdsale.withdrawTokens(address)[`withdrawTokens`] in order to claim the tokens they've purchased.
 
-```solidity
+[source,solidity]
+----
 contract MyCrowdsale is Crowdsale, TimedCrowdsale, PostDeliveryCrowdsale {
 
     constructor(
@@ -218,14 +216,15 @@ contract MyCrowdsale is Crowdsale, TimedCrowdsale, PostDeliveryCrowdsale {
         // and then users can `withdrawTokens()` to get the tokens they're owed
     }
 }
-```
-
-### RefundableCrowdsale
+----
 
-The [`RefundableCrowdsale`](api/crowdsale#refundablecrowdsale) offers to refund users if a minimum goal is not reached. If the goal is not reached, the users can [`claimRefund`](api/crowdsale#RefundableCrowdsale.claimRefund(address%20payable)) to get their Ether back.
+[[refundablecrowdsale]]
+=== RefundableCrowdsale
 
+The link:api/crowdsale#refundablecrowdsale[`RefundableCrowdsale`] offers to refund users if a minimum goal is not reached. If the goal is not reached, the users can link:api/crowdsale#RefundableCrowdsale.claimRefund(address%20payable)[`claimRefund`] to get their Ether back.
 
-```solidity
+[source,solidity]
+----
 contract MyCrowdsale is Crowdsale, RefundableCrowdsale {
 
     constructor(
@@ -242,4 +241,4 @@ contract MyCrowdsale is Crowdsale, RefundableCrowdsale {
         // by calling claimRefund(...)
     }
 }
-```
+----

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

@@ -1,66 +1,70 @@
----
-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.
+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

@@ -0,0 +1,70 @@
+= 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

@@ -0,0 +1,17 @@
+= 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/tokens.md → docs/modules/ROOT/pages/tokens.adoc

@@ -1,13 +1,10 @@
----
-id: tokens
-title: Tokens
----
+= Tokens
 
 Ah, the "token": the world's most powerful and most misunderstood tool.
 
 A token is a _representation of something in the blockchain_. This something can be money, time, services, shares in a company, a virtual pet, anything. By representing things as tokens, we can allow smart contracts to interact with them, exchange them, create or destroy them.
 
-## But First, ~~Coffee~~ a Primer on Token Contracts
+== But First, [line-through]*Coffee* a Primer on Token Contracts
 
 Much of the confusion surrounding tokens comes from two concepts getting mixed up: _token contracts_ and the actual _tokens_.
 
@@ -15,32 +12,33 @@ A _token contract_ is simply an Ethereum smart contract. "Sending tokens" actual
 
 It is these balances that represent the _tokens_ themselves. Someone "has tokens" when their balance in the token contract is non-zero. That's it! These balances could be considered money, experience points in a game, deeds of ownership, or voting rights, and each of these tokens would be stored in different token contracts.
 
-### Different kinds of tokens
+=== Different kinds of tokens
 
-Note that there's a big difference between having two voting rights and two deeds of ownership: each vote is equal to all others, but houses usually are not! This is called [fungibility](https://en.wikipedia.org/wiki/Fungibility). _Fungible goods_  are equivalent and interchangeable, like Ether, fiat currencies, and voting rights. _Non-fungible_ goods are unique and distinct, like deeds of ownership, or collectibles.
+Note that there's a big difference between having two voting rights and two deeds of ownership: each vote is equal to all others, but houses usually are not! This is called https://en.wikipedia.org/wiki/Fungibility[fungibility]. _Fungible goods_ are equivalent and interchangeable, like Ether, fiat currencies, and voting rights. _Non-fungible_ goods are unique and distinct, like deeds of ownership, or collectibles.
 
 In a nutshell, when dealing with non-fungibles (like your house) you care about _which ones_ you have, while in fungible assets (like your bank account statement) what matters is _how much_ you have.
 
-### Standards
+=== Standards
 
-Even though the concept of a token is simple, they have a variety of complexities in the implementation. Because everything in Ethereum is just a smart contract, and there are no rules about what smart contracts have to do, the community has developed a variety of **standards** (called EIPs or ERCs) for documenting how a contract can interoperate with other contracts.
+Even though the concept of a token is simple, they have a variety of complexities in the implementation. Because everything in Ethereum is just a smart contract, and there are no rules about what smart contracts have to do, the community has developed a variety of *standards* (called EIPs or ERCs) for documenting how a contract can interoperate with other contracts.
 
-You've probably heard of the [ERC20](#erc20) or [ERC721](#erc721) token standards, and that's why you're here.
+You've probably heard of the <<ERC20>> or <<ERC721>> token standards, and that's why you're here.
 
+[[ERC20]]
+== ERC20
 
-## ERC20
+An ERC20 token contract keeps track of link:#different-kinds-of-tokens[_fungible_ tokens]: any one token is exactly equal to any other token; no tokens have special rights or behavior associated with them. This makes ERC20 tokens useful for things like a *medium of exchange currency*, *voting rights*, *staking*, and more.
 
-An ERC20 token contract keeps track of [_fungible_ tokens](#different-kinds-of-tokens): any one token is exactly equal to any other token; no tokens have special rights or behavior associated with them. This makes ERC20 tokens useful for things like a **medium of exchange currency**, **voting rights**, **staking**, and more.
+OpenZeppelin provides many ERC20-related contracts. On the xref:api:token/ERC20.adoc[`API reference`] you'll find detailed information on their properties and usage.
 
-OpenZeppelin provides many ERC20-related contracts. On the [`API reference`](api/token/ERC20) you'll find detailed information on their properties and usage.
-
-### Constructing an ERC20 Token Contract
+=== Constructing an ERC20 Token Contract
 
 Using OpenZeppelin, we can easily create our own ERC20 token contract, which will be used to track _Gold_ (GLD), an internal currency in a hypothetical game.
 
 Here's what our GLD token might look like.
 
-```solidity
+[source,solidity]
+----
 pragma solidity ^0.5.0;
 
 import "openzeppelin-solidity/contracts/token/ERC20/ERC20.sol";
@@ -51,34 +49,36 @@ contract GLDToken is ERC20, ERC20Detailed {
         _mint(msg.sender, initialSupply);
     }
 }
-```
+----
 
-OpenZeppelin contracts are often used via [inheritance](https://solidity.readthedocs.io/en/latest/contracts.html#inheritance), and here we're reusing [`ERC20`](api/token/ERC20#erc20) for the basic standard implementation and [`ERC20Detailed`](api/token/ERC20#erc20detailed) to get the [`name`](api/token/ERC20#ERC20Detailed.name()), [`symbol`](api/token/ERC20#ERC20Detailed.symbol()), and [`decimals`](api/token/ERC20#ERC20Detailed.decimals()) properties. Additionally, we're creating an `initialSupply` of tokens, which will be assigned to the address that deploys the contract.
+OpenZeppelin contracts are often used via https://solidity.readthedocs.io/en/latest/contracts.html#inheritance[inheritance], and here we're reusing xref:api:token/ERC20.adoc#erc20[`ERC20`] for the basic standard implementation and xref:api:token/ERC20.adoc#ERC20Detailed[`ERC20Detailed`] to get the xref:api:token/ERC20.adoc#ERC20Detailed-name[`name`], xref:api:token/ERC20.adoc#ERC20Detailed-symbol[`symbol`], and xref:api:token/ERC20.adoc#ERC20Detailed-decimals[`decimals`] properties. Additionally, we're creating an `initialSupply` of tokens, which will be assigned to the address that deploys the contract.
 
-_For a more complete discussion of ERC20 supply mechanisms, see [our advanced guide](erc20-supply)_.
+TIP: For a more complete discussion of ERC20 supply mechanisms, see xref:erc20-supply.adoc[our advanced guide].
 
 That's it! Once deployed, we will be able to query the deployer's balance:
 
-```javascript
+[source,javascript]
+----
 > GLDToken.balanceOf(deployerAddress)
 1000
-```
+----
 
-We can also [transfer](api/token/ERC20#IERC20.transfer(address,uint256)) these tokens to other accounts:
+We can also xref:api:token/ERC20.adoc#IERC20-transfer-address-uint256[transfer] these tokens to other accounts:
 
-```javascript
+[source,javascript]
+----
 > GLDToken.transfer(otherAddress, 300)
 > GLDToken.balanceOf(otherAddress)
 300
 > GLDToken.balanceOf(deployerAddress)
 700
-```
+----
 
-### A note on `decimals`
+=== A note on `decimals`
 
 Often, you'll want to be able to divide your tokens into arbitrary amounts: say, if you own `5 GLD`, you may want to send `1.5 GLD` to a friend, and keep `3.5 GLD` to yourself. Unfortunately, Solidity and the EVM do not support this behavior: only integer (whole) numbers can be used, which poses an issue. You may send `1` or `2` tokens, but not `1.5`.
 
-To work around this, [`ERC20Detailed`](api/token/ERC20#erc20detailed) provides a [`decimals`](api/token/ERC20#ERC20Detailed.decimals()) field, which is used to specify how many decimal places a token has. To be able to transfer `1.5 GLD`, `decimals` must be at least `1`, since that number has a single decimal place.
+To work around this, xref:api:token/ERC20.adoc#erc20detailed[`ERC20Detailed`] provides a xref:api:token/ERC20.adoc#ERC20Detailed.decimals()[`decimals`] field, which is used to specify how many decimal places a token has. To be able to transfer `1.5 GLD`, `decimals` must be at least `1`, since that number has a single decimal place.
 
 How can this be achieved? It's actually very simple: a token contract can use larger integer values, so that a balance of `50` will represent `5 GLD`, a transfer of `15` will correspond to `1.5 GLD` being sent, and so on.
 
@@ -86,20 +86,21 @@ It is important to understand that `decimals` is _only used for display purposes
 
 You'll probably want to use a `decimals` value of `18`, just like Ether and most ERC20 token contracts in use, unless you have a very special reason not to. When minting tokens or transferring them around, you will be actually sending the number `num GLD * 10**decimals`. So if you want to send `5` tokens using a token contract with 18 decimals, the the method to call will actually be `transfer(recipient, 5 * 10**18)`.
 
+[[ERC721]]
+== ERC721
 
-## ERC721
-
-We've discussed how you can make a _fungible_ token using [ERC20](#erc20), but what if not all tokens are alike? This comes up in situations like **real estate** or **collectibles**, where some items are valued more than others, due to their usefulness, rarity, etc. ERC721 is a standard for representing ownership of [_non-fungible_ tokens](#different-kinds-of-tokens), that is, where each token is unique.
+We've discussed how you can make a _fungible_ token using link:#erc20[ERC20], but what if not all tokens are alike? This comes up in situations like *real estate* or *collectibles*, where some items are valued more than others, due to their usefulness, rarity, etc. ERC721 is a standard for representing ownership of link:#different-kinds-of-tokens[_non-fungible_ tokens], that is, where each token is unique.
 
-ERC721 is a more complex standard than ERC20, with multiple optional extensions, and is split accross a number of contracts. OpenZeppelin provides flexibility regarding how these are combined, along with custom useful extensions. Check out the [`API reference`](api/token/ERC721) to learn more about these.
+ERC721 is a more complex standard than ERC20, with multiple optional extensions, and is split accross a number of contracts. OpenZeppelin provides flexibility regarding how these are combined, along with custom useful extensions. Check out the xref:api:token/ERC721.adoc[`API reference`] to learn more about these.
 
-### Constructing an ERC721 Token Contract
+=== Constructing an ERC721 Token Contract
 
 We'll use ERC721 to track items in our game, which will each have their own unique attributes. Whenever one is to be awarded to a player, it will be minted and sent to them. Players are free to keep their token or trade it with other people as they see fit, as they would any other asset on the blockchain!
 
 Here's what a contract for tokenized items might look like:
 
-```solidity
+[source,solidity]
+----
 pragma solidity ^0.5.0;
 
 import "openzeppelin-solidity/contracts/token/ERC721/ERC721Full.sol";
@@ -122,67 +123,73 @@ contract GameItem is ERC721Full {
         return newItemId;
     }
 }
-```
+----
 
-The [`ERC721Full`](api/token/ERC721#erc721full) contract includes all standard extensions, and is probably the one you want to use. In particular, it includes [`ERC721Metadata`](api/token/ERC721#erc721metadata), which provides the [`_setTokenURI`](api/token/ERC721#ERC721Metadata._setTokenURI(uint256,string)) method we use to store an item's metadata.
+The xref:api:token/ERC721.adoc#erc721full[`ERC721Full`] contract includes all standard extensions, and is probably the one you want to use. In particular, it includes xref:api:token/ERC721.adoc#erc721metadata[`ERC721Metadata`], which provides the xref:api:token/ERC721.adoc#ERC721Metadata._setTokenURI(uint256,string)[`_setTokenURI`] method we use to store an item's metadata.
 
 Also note that, unlike ERC20, ERC721 lacks a `decimals` field, since each token is distinct and cannot be partitioned.
 
 New items can be created:
 
-```javascript
+[source,javascript]
+----
 > gameItem.awardItem(playerAddress, "https://game.example/item-id-8u5h2m.json")
 7
-```
+----
 
 And the owner and metadata of each item queried:
-```javascript
+
+[source,javascript]
+----
 > gameItem.ownerOf(7)
 playerAddress
 > gameItem.tokenURI(7)
 "https://game.example/item-id-8u5h2m.json"
-```
+----
 
 This `tokenURI` should resolve to a JSON document that might look something like:
 
-```json
+[source,json]
+----
 {
     "name": "Thor's hammer",
     "description": "Mjölnir, the legendary hammer of the Norse god of thunder.",
     "image": "https://game.example/item-id-8u5h2m.png",
     "strength": 20
 }
-```
+----
 
-For more information about the `tokenURI` metadata JSON Schema, check out the [ERC721 specification](https://eips.ethereum.org/EIPS/eip-721).
+For more information about the `tokenURI` metadata JSON Schema, check out the https://eips.ethereum.org/EIPS/eip-721[ERC721 specification].
 
 _Note: you'll notice that the item's information is included in the metadata, but that information isn't on-chain! So a game developer could change the underlying metadata, changing the rules of the game! If you'd like to put all item information on-chain, you can extend ERC721 to do so (though it will be rather costly). You could also leverage IPFS to store the tokenURI information, but these techniques are out of the scope of this overview guide._
 
+== Advanced standards
 
-# Advanced standards
-
-[ERC20](#erc20) and [ERC721](#erc721) (fungible and non-fungible assets, respectively) are the first two token contract standards to enjoy widespread use and adoption, but over time, multiple weak points of these standards were identified, as more advanced use cases came up.
+link:#erc20[ERC20] and link:#erc721[ERC721] (fungible and non-fungible assets, respectively) are the first two token contract standards to enjoy widespread use and adoption, but over time, multiple weak points of these standards were identified, as more advanced use cases came up.
 
 As a result, a multitude of new token standards were and are still being developed, with different tradeoffs between complexity, compatibility and ease of use. We'll explore some of those here.
 
-## ERC777
+[[ERC777]]
+== ERC777
 
-Like ERC20, ERC777 is a standard for [_fungible_ tokens](#different-kinds-of-tokens), and is focused around allowing more complex interactions when trading tokens. More generally, it brings tokens and Ether closer together by providing the equivalent of a `msg.value` field, but for tokens.
+Like ERC20, ERC777 is a standard for link:#different-kinds-of-tokens[_fungible_ tokens], and is focused around allowing more complex interactions when trading tokens. More generally, it brings tokens and Ether closer together by providing the equivalent of a `msg.value` field, but for tokens.
 
-The standard also bring multiple quality-of-life improvements, such as getting rid of the confusion around `decimals`, minting and burning with proper events, among others, but its killer feature are **receive hooks**. A hook is simply a function in a contract that is called when tokens are sent to it, meaning **accounts and contracts can react to receiving tokens**.
+The standard also bring multiple quality-of-life improvements, such as getting rid of the confusion around `decimals`, minting and burning with proper events, among others, but its killer feature are *receive hooks*. A hook is simply a function in a contract that is called when tokens are sent to it, meaning *accounts and contracts can react to receiving tokens*.
 
-This enables a lot of interesting use cases, including atomic purchases using tokens (no need to do `approve` and `transferFrom` in two separate transactions), rejecting reception of tokens (by reverting on the hook call), redirecting the received tokens to other addresses (similarly to how [`PaymentSplitter`](api/payment#paymentsplitter) does it), among many others.
+This enables a lot of interesting use cases, including atomic purchases using tokens (no need to do `approve` and `transferFrom` in two separate transactions), rejecting reception of tokens (by reverting on the hook call), redirecting the received tokens to other addresses (similarly to how xref:api:payment#paymentsplitter[`PaymentSplitter`] does it), among many others.
 
 Furthermore, since contracts are required to implement these hooks in order to receive tokens, _no tokens can get stuck in a contract that is unaware of the ERC777 protocol_, as has happened countless times when using ERC20s.
 
-### What if I already use ERC20?
-The standard has you covered! The ERC777 standard is **backwards compatible with ERC20**, meaning you can interact with these tokens as if they were ERC20, using the standard functions, while still getting all of the niceties, including send hooks. See the [EIP's Backwards Compatibility section](https://eips.ethereum.org/EIPS/eip-777#backward-compatibility) to learn more.
+=== What if I already use ERC20?
+
+The standard has you covered! The ERC777 standard is *backwards compatible with ERC20*, meaning you can interact with these tokens as if they were ERC20, using the standard functions, while still getting all of the niceties, including send hooks. See the https://eips.ethereum.org/EIPS/eip-777#backward-compatibility[EIP's Backwards Compatibility section] to learn more.
 
-### Constructing an ERC777 Token Contract
+=== Constructing an ERC777 Token Contract
 
-We will replicate the `GLD` example of the [ERC20 guide](#constructing-an-erc20-token-contract), this time using ERC777. As always, check out the [`API reference`](api/token/ERC777) to learn more about the details of each function.
+We will replicate the `GLD` example of the link:#constructing-an-erc20-token-contract[ERC20 guide], this time using ERC777. As always, check out the xref:api:token/ERC777.adoc[`API reference`] to learn more about the details of each function.
 
-```solidity
+[source,solidity]
+----
 pragma solidity ^0.5.0;
 
 import "openzeppelin-solidity/contracts/token/ERC777/ERC777.sol";
@@ -198,41 +205,43 @@ contract GLDToken is ERC777 {
         _mint(msg.sender, msg.sender, initialSupply, "", "");
     }
 }
-```
+----
 
-In this case, we'll be extending from the [`ERC777`](api/token/ERC777#erc777) contract, which provides an implementation with compatibility support for ERC20. The API is quite similar to that of [`ERC777`](api/token/ERC777#erc777), and we'll once again make use of [`_mint`](api/token/ERC777#ERC777._mint(address,address,uint256,bytes,bytes)) to assign the `initialSupply` to the deployer account. Unlike [ERC20's `_mint`](api/token/ERC20#ERC20._mint(address,uint256)), this one includes some extra parameters, but you can safely ignore those for now.
+In this case, we'll be extending from the xref:api:token/ERC777.adoc#erc777[`ERC777`] contract, which provides an implementation with compatibility support for ERC20. The API is quite similar to that of xref:api:token/ERC777.adoc#erc777[`ERC777`], and we'll once again make use of xref:api:token/ERC777.adoc#ERC777._mint(address,address,uint256,bytes,bytes)[`_mint`] to assign the `initialSupply` to the deployer account. Unlike xref:api:token/ERC20.adoc#ERC20._mint(address,uint256)[ERC20's `_mint`], this one includes some extra parameters, but you can safely ignore those for now.
 
-You'll notice both [`name`](api/token/ERC777#IERC777.name()) and [`symbol`](api/token/ERC777#IERC777.symbol()) are assigned, but not [`decimals`](api/token/ERC777#ERC777.decimals()). The ERC777 specification makes it mandatory to include support for these functions (unlike ERC20, where it is optional and we had to include [`ERC20Detailed`](api/token/ERC20#erc20detailed)), but also mandates that `decimals` always returns a fixed value of `18`, so there's no need to set it ourselves. For a review of `decimals`'s role and importance, refer back to our [ERC20 guide](tokens#a-note-on-decimals).
+You'll notice both xref:api:token/ERC777.adoc#IERC777.name()[`name`] and xref:api:token/ERC777.adoc#IERC777.symbol()[`symbol`] are assigned, but not xref:api:token/ERC777.adoc#ERC777.decimals()[`decimals`]. The ERC777 specification makes it mandatory to include support for these functions (unlike ERC20, where it is optional and we had to include xref:api:token/ERC20.adoc#erc20detailed[`ERC20Detailed`]), but also mandates that `decimals` always returns a fixed value of `18`, so there's no need to set it ourselves. For a review of `decimals`'s role and importance, refer back to our link:tokens#a-note-on-decimals[ERC20 guide].
 
-Finally, we'll need to set the [`defaultOperators`](api/token/ERC777#IERC777.defaultOperators()): special accounts (usually other smart contracts) that will be able to transfer tokens on behalf of their holders. If you're not planning on using operators in your token, you can simply pass an empty array. _Stay tuned for an upcoming in-depth guide on ERC777 operators!_
+Finally, we'll need to set the xref:api:token/ERC777.adoc#IERC777.defaultOperators()[`defaultOperators`]: special accounts (usually other smart contracts) that will be able to transfer tokens on behalf of their holders. If you're not planning on using operators in your token, you can simply pass an empty array. _Stay tuned for an upcoming in-depth guide on ERC777 operators!_
 
-That's it for a basic token contract! We can now deploy it, and use the same [`balanceOf`](api/token/ERC777#IERC777.balanceOf(address)) method to query the deployer's balance:
+That's it for a basic token contract! We can now deploy it, and use the same xref:api:token/ERC777.adoc#IERC777.balanceOf(address)[`balanceOf`] method to query the deployer's balance:
 
-```javascript
+[source,javascript]
+----
 > GLDToken.balanceOf(deployerAddress)
 1000
-```
+----
 
-To move tokens from one account to another, we can use both [`ERC20`'s `transfer`](api/token/ERC777#ERC777.transfer(address,uint256)) method, or the new [`ERC777`'s `send`](api/token/ERC777#ERC777.send(address,uint256,bytes)), which fulfills a very similar role, but adds an optional `data` field:
+To move tokens from one account to another, we can use both xref:api:token/ERC777.adoc#ERC777.transfer(address,uint256)[`ERC20`'s `transfer`] method, or the new xref:api:token/ERC777.adoc#ERC777.send(address,uint256,bytes)[`ERC777`'s `send`], which fulfills a very similar role, but adds an optional `data` field:
 
-```javascript
+[source,javascript]
+----
 > GLDToken.transfer(otherAddress, 300)
 > GLDToken.send(otherAddress, 300, "")
 > GLDToken.balanceOf(otherAddress)
 600
 > GLDToken.balanceOf(deployerAddress)
 400
-```
-
+----
 
-### Contract recipients
+=== Contract recipients
 
-A key difference when using [`send`](api/token/ERC777#ERC777.send(address,uint256,bytes)) is that token transfers to other contracts may revert with the following message:
+A key difference when using xref:api:token/ERC777.adoc#ERC777.send(address,uint256,bytes)[`send`] is that token transfers to other contracts may revert with the following message:
 
-```text
+[source,text]
+----
 ERC777: token recipient contract has no implementer for ERC777TokensRecipient
-```
+----
 
-This is a good thing! It means that the recipient contract has not registered itself as aware of the ERC777 protocol, so transfers to it are disabled to **prevent tokens from being locked forever**. As an example, [the Golem contract currently holds over 350k `GNT` tokens](https://etherscan.io/token/0xa74476443119A942dE498590Fe1f2454d7D4aC0d?a=0xa74476443119A942dE498590Fe1f2454d7D4aC0d), worth multiple tens of thousands of dollars, and lacks methods to get them out of there. This has happened to virtually every ERC20-backed project, usually due to user error.
+This is a good thing! It means that the recipient contract has not registered itself as aware of the ERC777 protocol, so transfers to it are disabled to *prevent tokens from being locked forever*. As an example, https://etherscan.io/token/0xa74476443119A942dE498590Fe1f2454d7D4aC0d?a=0xa74476443119A942dE498590Fe1f2454d7D4aC0d[the Golem contract currently holds over 350k `GNT` tokens], worth multiple tens of thousands of dollars, and lacks methods to get them out of there. This has happened to virtually every ERC20-backed project, usually due to user error.
 
 _An upcoming guide will cover how a contract can register itself as a recipient, send and receive hooks, and other advanced features of ERC777!_

docs/modules/ROOT/pages/utilities.adoc

@@ -0,0 +1,95 @@
+= 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

@@ -0,0 +1,3 @@
+{{#links}}
+:{{slug target.fullName}}: pass:normal[xref:{{path}}#{{target.anchor}}[`{{target.fullName}}`]]
+{{/links}}

docs/release-schedule.md

@@ -1,18 +0,0 @@
----
-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

@@ -1,24 +0,0 @@
-{
-  "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

@@ -1,94 +0,0 @@
----
-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

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-
-OUTDIR=docs/api
-
-rm -rf "$OUTDIR"
-solidity-docgen -o "$OUTDIR" -i contracts/mocks -i contracts/examples

scripts/docsite.sh

@@ -1,15 +1,16 @@
 #!/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

@@ -0,0 +1,13 @@
+#!/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"