docs

packages/contracts/README.adoc

@@ -0,0 +1,16 @@
+= The title here
+
+This is for testing purposes.
+
+== Core
+
+{{TokenVoting}}
+
+{{MajorityVotingBase}}
+
+{{TokenVotingSetup}}
+
+{{VotingPowerCondition}}
+
+
+

packages/contracts/hardhat.config.ts

@@ -179,13 +179,7 @@ const config: HardhatUserConfig = {
     outDir: 'typechain',
     target: 'ethers-v5',
   },
-  docgen: {
-    outputDir: 'docs',
-    theme: 'markdown',
-    pages: 'files',
-    collapseNewlines: true,
-    exclude: ['test', 'mocks'],
-  },
+  docgen: require('./docs/config.js'),
 };
 
 export default config;

packages/contracts/package.json

@@ -9,6 +9,7 @@
     "lint:ts": "cd ../../ && yarn run lint:contracts:ts",
     "test": "hardhat test",
     "docgen": "hardhat docgen",
+    "docs": "scripts/prepare-docs.sh",
     "typechain": "cross-env TS_NODE_TRANSPILE_ONLY=true hardhat typechain",
     "clean": "rimraf ./artifacts ./cache ./coverage ./typechain ./types ./coverage.json && yarn typechain"
   },
@@ -54,7 +55,8 @@
     "tmp-promise": "^3.0.3",
     "ts-node": "^10.9.1",
     "typechain": "^8.3.2",
-    "typescript": "^5.2.2"
+    "typescript": "^5.2.2",
+    "lodash.startcase": "^4.4.0"
   },
   "files": [
     "/src"

packages/contracts/scripts/gen-nav.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const glob = require('glob');
+const startCase = require('lodash.startcase');
+
+const baseDir = process.argv[2];
+
+const files = glob
+  .sync(baseDir + '/**/*.adoc')
+  .map(f => path.relative(baseDir, f));
+
+console.log('.API');
+
+function getPageTitle(directory) {
+  switch (directory) {
+    case 'metatx':
+      return 'Meta Transactions';
+    case 'common':
+      return 'Common (Tokens)';
+    default:
+      return startCase(directory);
+  }
+}
+
+const links = files.map(file => {
+  const doc = file.replace(baseDir, '');
+  const title = path.parse(file).name;
+
+  return {
+    xref: `* xref:${doc}[${getPageTitle(title)}]`,
+    title,
+  };
+});
+
+// Case-insensitive sort based on titles (so 'token/ERC20' gets sorted as 'erc20')
+const sortedLinks = links.sort(function (a, b) {
+  return a.title
+    .toLowerCase()
+    .localeCompare(b.title.toLowerCase(), undefined, {numeric: true});
+});
+
+for (const link of sortedLinks) {
+  console.log(link.xref);
+}

packages/contracts/scripts/prepare-docs.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+# shopt -s globstar
+
+OUTDIR="$(node -p 'require("./docs/config.js").outputDir')"
+
+if [ ! -d node_modules ]; then
+  npm ci
+fi
+
+rm -rf "$OUTDIR"
+
+hardhat docgen
+
+# copy examples and adjust imports
+# examples_source_dir="contracts/mocks/docs"
+# examples_target_dir="docs/modules/api/examples"
+
+# for f in "$examples_source_dir"/**/*.sol; do
+#   name="${f/#"$examples_source_dir/"/}"
+#   mkdir -p "$examples_target_dir/$(dirname "$name")"
+#   sed -Ee '/^import/s|"(\.\./)+|"@openzeppelin/contracts/|' "$f" > "$examples_target_dir/$name"
+# done
+
+echo $OUTDIR
+
+node scripts/gen-nav.js "$OUTDIR" > "$OUTDIR/../nav.adoc"

packages/contracts/yarn.lock

@@ -4980,6 +4980,11 @@ lodash.merge@^4.6.2:
   resolved "https://registry.yarnpkg.com/lodash.merge/-/lodash.merge-4.6.2.tgz#558aa53b43b661e1925a0afdfa36a9a1085fe57a"
   integrity sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==
 
+lodash.startcase@^4.4.0:
+  version "4.4.0"
+  resolved "https://registry.yarnpkg.com/lodash.startcase/-/lodash.startcase-4.4.0.tgz#9436e34ed26093ed7ffae1936144350915d9add8"
+  integrity sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==
+
 lodash.truncate@^4.4.2:
   version "4.4.2"
   resolved "https://registry.yarnpkg.com/lodash.truncate/-/lodash.truncate-4.4.2.tgz#5a350da0b1113b837ecfffd5812cbe58d6eae193"