Move the doc generation (with NPM) out of the root project

.gitignore

@@ -16,6 +16,7 @@ foundry-docs/
 
 # Node modules
 node_modules/
+docs-gen/bun.lock
 .DS_Store
 src/.DS_Store
 

.solhint.json

@@ -1,19 +1,12 @@
 {
   "extends": "solhint:recommended",
-  "plugins": ["prettier"],
   "rules": {
     "code-complexity": ["error", 9],
     "compiler-version": ["error", ">=0.8.4"],
     "func-visibility": ["error", {"ignoreConstructors": true}],
     "max-line-length": ["error", 120],
     "named-parameters-mapping": "off",
     "no-console": "off",
-    "not-rely-on-time": "off",
-    "prettier/prettier": [
-      "error",
-      {
-        "endOfLine": "auto"
-      }
-    ]
+    "not-rely-on-time": "off"
   }
 }

.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "prettier.documentSelectors": ["**/*.sol"],
+  "solidity.formatter": "forge",
+  "editor.tabSize": 4,
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[solidity]": {
+    "editor.defaultFormatter": "JuanBlanco.solidity"
+  }
+}

.zed/settings.json

@@ -0,0 +1,13 @@
+{
+  "languages": {
+    "Solidity": {
+      "format_on_save": "on",
+      "formatter": {
+        "external": {
+          "command": "forge",
+          "arguments": ["fmt", "-", "--raw"]
+        }
+      }
+    }
+  }
+}

docs-gen/bunfig.toml

@@ -0,0 +1,2 @@
+[install]
+lifecycle-scripts = false

docs-gen/package.json

@@ -0,0 +1,16 @@
+{
+    "private": true,
+    "version": "1.1",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/aragon/staged-proposal-processor-plugin"
+    },
+    "devDependencies": {
+        "@aragon/osx-commons-configs": "^1.4.6",
+        "fs-extra": "^11.0.0",
+        "glob": "^8.0.0",
+        "lodash.startcase": "^4.4.0",
+        "solc": "^0.8.28",
+        "solidity-docgen": "^0.6.0-beta.36"
+    }
+}

docs-gen/prepare-docs.js

@@ -0,0 +1,121 @@
+const docgen = require("solidity-docgen/dist/main");
+
+const { readdir } = require("node:fs/promises");
+const { join } = require("node:path");
+const path = require("path");
+const fs = require("fs-extra");
+const solc = require("solc");
+const glob = require("glob");
+const startCase = require("lodash.startcase");
+const { version, repository } = require("./package.json");
+
+const ROOT_DIR = path.resolve(__dirname, "..");
+
+const walk = async (dirPath) =>
+    Promise.all(
+        await readdir(dirPath, { withFileTypes: true }).then((entries) =>
+            entries.map((entry) => {
+                const childPath = join(dirPath, entry.name);
+                return entry.isDirectory() ? walk(childPath) : childPath;
+            }),
+        ),
+    );
+
+let includePaths = [path.join(__dirname, "node_modules")];
+
+function resolveImports(filePath) {
+    for (const includePath of includePaths) {
+        const fullPath = path.resolve(includePath, filePath);
+        if (fs.existsSync(fullPath)) {
+            return { contents: fs.readFileSync(fullPath, "utf8") };
+        }
+    }
+    return { error: `File not found: ${filePath}` };
+}
+
+const compile = async (filePaths) => {
+    const compilerInput = {
+        language: "Solidity",
+        sources: filePaths.reduce((input, fileName) => {
+            const source = fs.readFileSync(fileName, "utf8");
+            return { ...input, [fileName]: { content: source } };
+        }, {}),
+        settings: {
+            outputSelection: {
+                "*": {
+                    "*": ["*"],
+                    "": ["ast"],
+                },
+            },
+        },
+    };
+
+    return {
+        output: JSON.parse(
+            solc.compile(JSON.stringify(compilerInput), {
+                import: resolveImports,
+            }),
+        ),
+        input: compilerInput,
+    };
+};
+
+function generateNav(pagesDir) {
+    const files = glob
+        .sync(pagesDir + "/**/*.adoc")
+        .map((f) => path.relative(pagesDir, f));
+
+    function getPageTitle(name) {
+        switch (name) {
+            case "metatx": return "Meta Transactions";
+            case "common": return "Common (Tokens)";
+            default: return startCase(name);
+        }
+    }
+
+    const links = files
+        .map((file) => ({ xref: `* xref:${file}[${getPageTitle(path.parse(file).name)}]`, title: path.parse(file).name }))
+        .sort((a, b) => a.title.toLowerCase().localeCompare(b.title.toLowerCase(), undefined, { numeric: true }));
+
+    return [".API", ...links.map((l) => l.xref)].join("\n") + "\n";
+}
+
+async function main() {
+    const contractPath = path.resolve(ROOT_DIR, "src");
+    const allFiles = await walk(contractPath);
+
+    const solFiles = allFiles.flat(Number.POSITIVE_INFINITY).filter((item) => {
+        return path.extname(item).toLowerCase() == ".sol";
+    });
+
+    const { input, output } = await compile(solFiles);
+
+    const templatesPath = path.resolve(ROOT_DIR, "docs/templates");
+    const apiPath = path.resolve(ROOT_DIR, "docs/modules/api");
+
+    const helpers = require(path.join(templatesPath, "helpers"));
+
+    // overwrite the functions.
+    helpers.version = () => `${version}`;
+    helpers.githubURI = () => repository.url;
+
+    const config = {
+        outputDir: `${apiPath}/pages`,
+        sourcesDir: contractPath,
+        templates: templatesPath,
+        exclude: ["mocks", "test"],
+        pageExtension: ".adoc",
+        collapseNewlines: true,
+        pages: (_, file, config) => {
+            return "StagedProposalProcessor" + config.pageExtension;
+        },
+    };
+
+    await docgen.main([{ input: input, output: await output }], config);
+
+    fs.writeFileSync(`${apiPath}/nav.adoc`, generateNav(`${apiPath}/pages`), "utf8");
+
+    fs.rm(templatesPath, { recursive: true, force: true }, () => {});
+}
+
+main();

docs-gen/prepare-docs.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+rm -rf "$ROOT/docs/templates"
+
+PACKAGE_PATH=$(bun -p "require.resolve('@aragon/osx-commons-configs')")
+TEMPLATES_PATH=$(dirname "$PACKAGE_PATH")/docs/templates
+
+[ -d "$TEMPLATES_PATH" ] || { echo "Error: templates not found at $TEMPLATES_PATH" >&2; exit 1; }
+
+mkdir -p "$ROOT/docs/templates"
+cp -r "$TEMPLATES_PATH" "$ROOT/docs"

justfile

@@ -1,17 +1,23 @@
 default: help
+
 import 'lib/just-foundry/justfile'
 
+# Generate Solidity documentation (requires bun)
+[group('docs')]
+docs:
+    cd docs-gen && bun install && bash prepare-docs.sh && bun prepare-docs.js
+
 DEPLOY_SCRIPT := "script/Deploy.s.sol:Deploy"
 
 # Publish a new SPP plugin version (deploys setup, prints DAO proposal calldata)
 [group('upgrade')]
 new-version *args:
     #!/usr/bin/env bash
     set -euo pipefail
-    source {{ENV_RESOLVE_LIB}} && env_load_network
+    source {{ ENV_RESOLVE_LIB }} && env_load_network
     mkdir -p logs
     LOG_FILE="logs/new-version-$NETWORK_NAME-$(date +"%y-%m-%d-%H-%M").log"
     just test 2>&1 | tee -a "$LOG_FILE"
-    just run script/NewVersion.s.sol:NewVersion {{args}} 2>&1 | tee -a "$LOG_FILE"
+    just run script/NewVersion.s.sol:NewVersion {{ args }} 2>&1 | tee -a "$LOG_FILE"
     echo "Logs saved in $LOG_FILE"
 

npm-artifacts/prepare-abi.sh

@@ -21,7 +21,7 @@ do
     CONTRACT_NAME=${SRC_FILE_NAME%".sol"}
     SRC_FILE_PATH=$BUILD_OUT_FOLDER/$SRC_FILE_NAME/${SRC_FILE_NAME%".sol"}.json
 
-    ABI=$(node -p "JSON.stringify(JSON.parse(fs.readFileSync(\"$SRC_FILE_PATH\").toString()).abi)")
+    ABI=$(bun -p "JSON.stringify(JSON.parse(fs.readFileSync(\"$SRC_FILE_PATH\").toString()).abi)")
 
     echo "const ${CONTRACT_NAME}ABI = $ABI as const;" >> $TARGET_ABI_FILE
     echo "export {${CONTRACT_NAME}ABI};" >> $TARGET_ABI_FILE