Update docs pipeline to solidity-docgen@0.6 (#3707)

(cherry picked from commit c526250)

contracts/governance/utils/Votes.sol

@@ -122,7 +122,7 @@ abstract contract Votes is IVotes, Context, EIP712 {
     /**
      * @dev Delegate all of `account`'s voting units to `delegatee`.
      *
-     * Emits events {DelegateChanged} and {DelegateVotesChanged}.
+     * Emits events {IVotes-DelegateChanged} and {IVotes-DelegateVotesChanged}.
      */
     function _delegate(address account, address delegatee) internal virtual {
         address oldDelegate = delegates(account);

contracts/token/ERC20/extensions/ERC20FlashMint.sol

@@ -73,7 +73,7 @@ abstract contract ERC20FlashMint is ERC20, IERC3156FlashLender {
      * amount + fee tokens and have them approved back to the token contract itself so
      * they can be burned.
      * @param receiver The receiver of the flash loan. Should implement the
-     * {IERC3156FlashBorrower.onFlashLoan} interface.
+     * {IERC3156FlashBorrower-onFlashLoan} interface.
      * @param token The token to be flash loaned. Only `address(this)` is
      * supported.
      * @param amount The amount of tokens to be loaned.

contracts/token/ERC20/extensions/ERC20Votes.sol

@@ -191,7 +191,7 @@ abstract contract ERC20Votes is IVotes, ERC20Permit {
     /**
      * @dev Move voting power when tokens are transferred.
      *
-     * Emits a {DelegateVotesChanged} event.
+     * Emits a {IVotes-DelegateVotesChanged} event.
      */
     function _afterTokenTransfer(
         address from,
@@ -206,7 +206,7 @@ abstract contract ERC20Votes is IVotes, ERC20Permit {
     /**
      * @dev Change delegation for `delegator` to `delegatee`.
      *
-     * Emits events {DelegateChanged} and {DelegateVotesChanged}.
+     * Emits events {IVotes-DelegateChanged} and {IVotes-DelegateVotesChanged}.
      */
     function _delegate(address delegator, address delegatee) internal virtual {
         address currentDelegate = delegates(delegator);

contracts/token/ERC20/utils/SafeERC20.sol

@@ -104,7 +104,7 @@ library SafeERC20 {
      */
     function _callOptionalReturn(IERC20 token, bytes memory data) private {
         // We need to perform a low level call here, to bypass Solidity's return data size checking mechanism, since
-        // we're implementing it ourselves. We use {Address.functionCall} to perform this call, which verifies that
+        // we're implementing it ourselves. We use {Address-functionCall} to perform this call, which verifies that
         // the target address contains contract code and also asserts for success in the low-level call.
 
         bytes memory returndata = address(token).functionCall(data, "SafeERC20: low-level call failed");

contracts/token/ERC721/extensions/ERC721Consecutive.sol

@@ -79,7 +79,7 @@ abstract contract ERC721Consecutive is IERC2309, ERC721 {
      *
      * CAUTION: Does not invoke `onERC721Received` on the receiver.
      *
-     * Emits a {ConsecutiveTransfer} event.
+     * Emits a {IERC2309-ConsecutiveTransfer} event.
      */
     function _mintConsecutive(address to, uint96 batchSize) internal virtual returns (uint96) {
         uint96 first = _totalConsecutiveSupply();

contracts/token/ERC721/extensions/ERC721Royalty.sol

@@ -11,8 +11,8 @@ import "../../../utils/introspection/ERC165.sol";
  * @dev Extension of ERC721 with the ERC2981 NFT Royalty Standard, a standardized way to retrieve royalty payment
  * information.
  *
- * Royalty information can be specified globally for all token ids via {_setDefaultRoyalty}, and/or individually for
- * specific token ids via {_setTokenRoyalty}. The latter takes precedence over the first.
+ * Royalty information can be specified globally for all token ids via {ERC2981-_setDefaultRoyalty}, and/or individually for
+ * specific token ids via {ERC2981-_setTokenRoyalty}. The latter takes precedence over the first.
  *
  * IMPORTANT: ERC-2981 only specifies a way to signal royalty information and does not enforce its payment. See
  * https://eips.ethereum.org/EIPS/eip-2981#optional-royalty-payments[Rationale] in the EIP. Marketplaces are expected to

contracts/token/ERC721/extensions/ERC721Votes.sol

@@ -20,7 +20,7 @@ abstract contract ERC721Votes is ERC721, Votes {
     /**
      * @dev Adjusts votes when tokens are transferred.
      *
-     * Emits a {Votes-DelegateVotesChanged} event.
+     * Emits a {IVotes-DelegateVotesChanged} event.
      */
     function _afterTokenTransfer(
         address from,
@@ -34,7 +34,7 @@ abstract contract ERC721Votes is ERC721, Votes {
     /**
      * @dev Adjusts votes when a batch of tokens is transferred.
      *
-     * Emits a {Votes-DelegateVotesChanged} event.
+     * Emits a {IVotes-DelegateVotesChanged} event.
      */
     function _afterConsecutiveTokenTransfer(
         address from,

contracts/token/ERC777/ERC777.sol

@@ -508,7 +508,7 @@ contract ERC777 is Context, IERC777, IERC20 {
      * Does not update the allowance amount in case of infinite allowance.
      * Revert if not enough allowance is available.
      *
-     * Might emit an {Approval} event.
+     * Might emit an {IERC20-Approval} event.
      */
     function _spendAllowance(
         address owner,

contracts/utils/structs/EnumerableMap.sol

@@ -145,10 +145,10 @@ library EnumerableMap {
     }
 
     /**
-     * @dev Same as {_get}, with a custom error message when `key` is not in the map.
+     * @dev Same as {get}, with a custom error message when `key` is not in the map.
      *
      * CAUTION: This function is deprecated because it requires allocating memory for the error
-     * message unnecessarily. For custom revert reasons use {_tryGet}.
+     * message unnecessarily. For custom revert reasons use {tryGet}.
      */
     function get(
         Bytes32ToBytes32Map storage map,

docs/config.js

@@ -0,0 +1,21 @@
+const path = require('path');
+const fs = require('fs');
+
+/** @type import('solidity-docgen/dist/config').UserConfig */
+module.exports = {
+  outputDir: 'docs/modules/api/pages',
+  templates: 'docs/templates',
+  exclude: ['mocks'],
+  pageExtension: '.adoc',
+  pages: (_, file, config) => {
+    // For each contract file, find the closest README.adoc and return its location as the output page path.
+    const sourcesDir = path.resolve(config.root, config.sourcesDir);
+    let dir = path.resolve(config.root, file.absolutePath);
+    while (dir.startsWith(sourcesDir)) {
+      dir = path.dirname(dir);
+      if (fs.existsSync(path.join(dir, 'README.adoc'))) {
+        return path.relative(sourcesDir, dir) + config.pageExtension;
+      }
+    }
+  },
+};

docs/templates/contract.hbs

@@ -0,0 +1,85 @@
+{{#each items}}
+:{{name}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]]
+{{/each}}
+
+[.contract]
+[[{{anchor}}]]
+=== `++{{name}}++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}[{github-icon},role=heading-link]
+
+[.hljs-theme-light.nopadding]
+```solidity
+import "@openzeppelin/{{__item_context.file.absolutePath}}";
+```
+
+{{{natspec.dev}}}
+
+{{#if modifiers}}
+[.contract-index]
+.Modifiers
+--
+{{#each modifiers}}
+* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`]
+{{/each}}
+--
+{{/if}}
+
+{{#if has-functions}}
+[.contract-index]
+.Functions
+--
+{{#each inherited-functions}}
+{{#unless @first}}
+[.contract-subindex-inherited]
+.{{contract.name}}
+{{/unless}}
+{{#each functions}}
+* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`]
+{{/each}}
+
+{{/each}}
+--
+{{/if}}
+
+{{#if has-events}}
+[.contract-index]
+.Events
+--
+{{#each inheritance}}
+{{#unless @first}}
+[.contract-subindex-inherited]
+.{{name}}
+{{/unless}}
+{{#each events}}
+* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`]
+{{/each}}
+
+{{/each}}
+--
+{{/if}}
+
+{{#each modifiers}}
+[.contract-item]
+[[{{anchor}}]]
+==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#modifier#
+
+{{{natspec.dev}}}
+
+{{/each}}
+
+{{#each functions}}
+[.contract-item]
+[[{{anchor}}]]
+==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}}){{#if returns}} → {{typed-params returns}}{{/if}}++` [.item-kind]#{{visibility}}#
+
+{{{natspec.dev}}}
+
+{{/each}}
+
+{{#each events}}
+[.contract-item]
+[[{{anchor}}]]
+==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#event#
+
+{{{natspec.dev}}}
+
+{{/each}}

docs/templates/helpers.js

@@ -0,0 +1,46 @@
+const { version } = require('../../package.json');
+
+module.exports['oz-version'] = () => version;
+
+module.exports['readme-path'] = (opts) => {
+  return 'contracts/' + opts.data.root.id.replace(/\.adoc$/, '') + '/README.adoc';
+};
+
+module.exports.names = (params) => params.map(p => p.name).join(', ');
+
+module.exports['typed-params'] = (params) => {
+  return params.map(p => `${p.type}${p.name ? ' ' + p.name : ''}`).join(', ');
+};
+
+const slug = module.exports.slug = (str) => {
+  if (str === undefined) {
+    throw new Error('Missing argument');
+  }
+  return str.replace(/\W/g, '-');
+};
+
+const linksCache = new WeakMap();
+
+function getAllLinks (items) {
+  if (linksCache.has(items)) {
+    return linksCache.get(items);
+  }
+  const res = {};
+  linksCache.set(items, res);
+  for (const item of items) {
+    res[`xref-${item.anchor}`] = `xref:${item.__item_context.page}#${item.anchor}`;
+    res[slug(item.fullName)] = `pass:normal[xref:${item.__item_context.page}#${item.anchor}[\`${item.fullName}\`]]`;
+  }
+  return res;
+}
+
+module.exports['with-prelude'] = (opts) => {
+  const links = getAllLinks(opts.data.site.items);
+  const contents = opts.fn();
+  const neededLinks = contents
+    .match(/\{[-._a-z0-9]+\}/ig)
+    .map(m => m.replace(/^\{(.+)\}$/, '$1'))
+    .filter(k => k in links);
+  const prelude = neededLinks.map(k => `:${k}: ${links[k]}`).join('\n');
+  return prelude + '\n' + contents;
+};

docs/templates/page.hbs

@@ -0,0 +1,4 @@
+:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
+{{#with-prelude}}
+{{readme (readme-path)}}
+{{/with-prelude}}