Add import statements and GitHub link in API docs (#2714)

docs/contract.hbs

@@ -8,7 +8,12 @@
 
 [.contract]
 [[{{anchor}}]]
-=== `++{{name}}++`
+=== `++{{name}}++` link:{{github-link file.path}}[{github-icon},role=heading-link]
+
+[.hljs-theme-light.nopadding]
+```solidity
+import "@openzeppelin/contracts/{{file.path}}";
+```
 
 {{natspec.devdoc}}
 

docs/helpers.js

@@ -0,0 +1,10 @@
+const { version } = require('../package.json');
+
+module.exports = {
+  'github-link': (contractPath) => {
+    if (typeof contractPath !== 'string') {
+      throw new Error('Missing argument');
+    }
+    return `https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v${version}/contracts/${contractPath}`;
+  },
+};

docs/prelude.hbs

@@ -1,3 +1,5 @@
+:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
+
 {{#links}}
 :{{slug target.fullName}}: pass:normal[xref:{{path}}#{{target.anchor}}[`{{target.fullName}}`]]
 :xref-{{slug target.anchor}}: xref:{{path}}#{{target.anchor}}

package.json

@@ -14,7 +14,7 @@
     "compile": "hardhat compile",
     "coverage": "hardhat coverage",
     "docs": "oz-docs",
-    "docs:watch": "npm run docs watch contracts 'docs/*.hbs'",
+    "docs:watch": "npm run docs watch contracts 'docs/*.hbs' docs/helpers.js",
     "prepare-docs": "scripts/prepare-docs.sh",
     "lint": "npm run lint:js && npm run lint:sol",
     "lint:fix": "npm run lint:js:fix && npm run lint:sol:fix",

scripts/prepare-docs.sh

@@ -15,6 +15,7 @@ solidity-docgen \
   -o "$OUTDIR" \
   -e contracts/mocks,contracts/examples \
   --output-structure readmes \
+  --helpers ./docs/helpers.js \
   --solc-module ./scripts/prepare-docs-solc.js
 
 node scripts/gen-nav.js "$OUTDIR" > "$OUTDIR/../nav.adoc"