Merge pull request #7 from hifi-finance/feat/add-solidity-docgen-config

feat: add docgen config

.eslintignore

@@ -8,7 +8,9 @@
 **/cache
 **/coverage
 **/dist
+**/docs
 **/node_modules
+**/templates
 **/types
 
 # files

.gitignore

@@ -13,6 +13,7 @@
 **/.coverage_cache
 **/.coverage_contracts
 **/dist
+**/docs
 **/node_modules
 
 # files

.prettierignore

@@ -9,6 +9,7 @@
 **/coverage
 **/dist
 **/node_modules
+**/templates
 **/types
 
 # files

hardhat.config.ts

@@ -3,7 +3,8 @@ import "@nomiclabs/hardhat-waffle";
 import { config as dotenvConfig } from "dotenv";
 import type { HardhatUserConfig } from "hardhat/config";
 import type { NetworkUserConfig } from "hardhat/types";
-import { resolve } from "path";
+import { relative, resolve } from "path";
+import "solidity-docgen";
 
 import "./tasks/deploy";
 
@@ -63,6 +64,14 @@ function getChainConfig(chain: keyof typeof chainIds): NetworkUserConfig {
 
 const config: HardhatUserConfig = {
   defaultNetwork: "hardhat",
+  docgen: {
+    templates: "./templates",
+    pages: (_item, file) => {
+      return file.absolutePath.startsWith("contracts")
+        ? relative("contracts", file.absolutePath).replace(".sol", ".md")
+        : undefined;
+    },
+  },
   etherscan: {
     apiKey: {
       arbitrumOne: process.env.ARBISCAN_API_KEY || "",

package.json

@@ -53,6 +53,7 @@
     "solhint": "^3.3.7",
     "solhint-plugin-prettier": "^0.0.5",
     "solidity-coverage": "^0.7.21",
+    "solidity-docgen": "^0.6.0-beta.35",
     "ts-generator": "^0.1.1",
     "ts-node": "^10.9.1",
     "typechain": "^8.1.0",
@@ -77,10 +78,11 @@
     "access": "public"
   },
   "scripts": {
-    "clean": "shx rm -rf ./artifacts ./cache ./coverage ./src/types ./coverage.json && yarn typechain",
+    "clean": "shx rm -rf ./artifacts ./cache ./coverage ./src/types ./coverage.json ./docs && yarn typechain",
     "commit": "git-cz",
     "compile": "cross-env TS_NODE_TRANSPILE_ONLY=true hardhat compile",
     "coverage": "hardhat coverage --solcoverjs ./.solcover.js --temp artifacts --testfiles \"test/**/*.ts\" && yarn typechain",
+    "generate:docs": "hardhat docgen && yarn prettier",
     "lint": "yarn lint:sol && yarn lint:ts && yarn prettier:check",
     "lint:sol": "solhint --config ./.solhint.json --max-warnings 0 \"contracts/**/*.sol\"",
     "lint:ts": "eslint --config ./.eslintrc.yml --ignore-path ./.eslintignore --ext .js,.ts .",

templates/contract.hbs

@@ -0,0 +1,35 @@
+{{h}} {{name}}
+
+{{{natspec.notice}}}
+
+{{{natspec.dev}}}
+
+{{#if functions}}
+{{h 2}} Functions
+{{/if}}
+
+{{#each functions}}
+{{#hsection 2}}
+{{>item}}
+{{/hsection}}
+{{/each}}
+
+{{#if events}}
+{{h 2}} Events
+{{/if}}
+
+{{#each events}}
+{{#hsection 2}}
+{{>item}}
+{{/hsection}}
+{{/each}}
+
+{{#if errors}}
+{{h 2}} Custom Errors
+{{/if}}
+
+{{#each errors}}
+{{#hsection 2}}
+{{>item}}
+{{/hsection}}
+{{/each}}

templates/event.hbs

@@ -0,0 +1,27 @@
+{{h}} {{name}}
+
+```solidity
+event {{name}}(
+    {{#params}}
+    {{type}} {{name}}{{#if @last}}{{else}},{{/if}}
+    {{/params}}
+)
+```
+
+{{#if natspec.notice}}
+{{{natspec.notice}}}
+{{/if}}
+
+{{#if natspec.dev}}
+{{{natspec.dev}}}
+{{/if}}
+
+{{#if params}}
+{{h 2}} Parameters
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+{{#each params}}
+| `{{name}}` | {{type}} | {{{natspec}}} |
+{{/each}}
+{{/if}}

templates/function.hbs

@@ -0,0 +1,38 @@
+{{h}} {{name}}
+
+```solidity
+function {{name}}({{#if params}}
+    {{#each params}}
+    {{type}} {{name}}{{#if @last}}{{else}},{{/if}}
+    {{/each}}
+{{/if}}) {{visibility}}{{#if returns}} returns ({{printParams returns}}){{/if}}
+```
+
+{{#if natspec.notice}}
+{{{natspec.notice}}}
+{{/if}}
+
+{{#if natspec.dev}}
+{{{natspec.dev}}}
+{{/if}}
+
+{{#if params}}
+#### Parameters
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+{{#each params}}
+| `{{name}}` | {{type}} | {{{natspec}}} |
+{{/each}}
+{{/if}}
+
+{{#if natspec.returns}}
+#### Return Values
+
+| Name | Type | Description |
+| :--- | :--- | :---------- |
+{{#each returns}}
+| `{{#if name}}{{name}}{{else}}[{{@index}}]{{/if}}` | {{type}} | {{{natspec}}} |
+{{/each}}
+{{/if}}
+

templates/helpers.js

@@ -0,0 +1,12 @@
+module.exports = {
+  printParams(params) {
+    const mappedParams = params.map(param => {
+      if (param.name) {
+        return `${param.type} ${param.name}`;
+      } else {
+        return param.type;
+      }
+    });
+    return mappedParams.join(", ");
+  },
+};

templates/page.hbs

@@ -0,0 +1,4 @@
+{{#each items}}
+{{>item}}
+
+{{/each}}

yarn.lock

@@ -1553,6 +1553,7 @@ __metadata:
     solhint: ^3.3.7
     solhint-plugin-prettier: ^0.0.5
     solidity-coverage: ^0.7.21
+    solidity-docgen: ^0.6.0-beta.35
     ts-generator: ^0.1.1
     ts-node: ^10.9.1
     typechain: ^8.1.0
@@ -8262,7 +8263,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"handlebars@npm:^4.0.1":
+"handlebars@npm:^4.0.1, handlebars@npm:^4.7.7":
   version: 4.7.7
   resolution: "handlebars@npm:4.7.7"
   dependencies:
@@ -13807,6 +13808,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"solidity-ast@npm:^0.4.38":
+  version: 0.4.46
+  resolution: "solidity-ast@npm:0.4.46"
+  checksum: 9c2ab90731fd23fdceef0e74ea626cc1810ec413daaa9b7d838f4fd9c342a63095fae0f0690ec0166db9f316ef6a06d7740a2c4f74cf5609831121389bf0cb7b
+  languageName: node
+  linkType: hard
+
 "solidity-comments-extractor@npm:^0.0.7":
   version: 0.0.7
   resolution: "solidity-comments-extractor@npm:0.0.7"
@@ -13842,6 +13850,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"solidity-docgen@npm:^0.6.0-beta.35":
+  version: 0.6.0-beta.35
+  resolution: "solidity-docgen@npm:0.6.0-beta.35"
+  dependencies:
+    handlebars: ^4.7.7
+    solidity-ast: ^0.4.38
+  peerDependencies:
+    hardhat: ^2.8.0
+  checksum: 5b773b8b2959109efca409ebd6eaa9eaa535989b52de7653bed75ad9195a145653c6436c258eb78cc819e220d79ecb4ed0efe9fcb8f9aed56e5b5d386149349d
+  languageName: node
+  linkType: hard
+
 "source-map-resolve@npm:^0.5.0":
   version: 0.5.3
   resolution: "source-map-resolve@npm:0.5.3"