From 6634f5ba3a591044dc83ef1e8c9e46a8d49233cd Mon Sep 17 00:00:00 2001 From: Psilon Date: Wed, 20 Oct 2021 13:55:19 +0300 Subject: [PATCH] initial version --- .npmrc | 2 + package.json | 21 ++++++-- utils/docify.utils.js | 118 ++++++++++++++++++++++++++++++++++++++++++ yarn.lock | 2 +- 4 files changed, 138 insertions(+), 5 deletions(-) create mode 100644 .npmrc create mode 100644 utils/docify.utils.js diff --git a/.npmrc b/.npmrc new file mode 100644 index 00000000..ebe1d424 --- /dev/null +++ b/.npmrc @@ -0,0 +1,2 @@ +registry=https://registry.npmjs.org +always-auth=true diff --git a/package.json b/package.json index 2d871a82..65eba1d8 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,10 @@ { - "name": "1inch-solidity-utils", - "version": "1.0.0", + "name": "@1inch/1inch-solidity-utils", + "version": "1.1.0", "main": "index.js", "repository": { "type": "git", - "url": "git@github.com:1inch/1inch-solidity-utils.git" + "url": "git+ssh://git@github.com/1inch/1inch-solidity-utils.git" }, "license": "MIT", "dependencies": { @@ -16,6 +16,7 @@ "@nomiclabs/hardhat-web3": "^2.0.0", "@openzeppelin/test-helpers": "^0.5.13", "chai": "^4.3.4", + "cross-spawn": "^7.0.3", "dotenv": "^10.0.0", "eslint": "^7.32.0", "eslint-config-standard": "^16.0.3", @@ -31,6 +32,9 @@ "solhint": "^3.3.6", "solidity-coverage": "^0.7.17" }, + "bin": { + "solidity-utils-docify": "utils/docify.utils.js" + }, "scripts": { "coverage": "hardhat coverage", "lint": "yarn run lint:js && yarn run lint:sol", @@ -40,5 +44,14 @@ "lint:sol": "solhint --max-warnings 0 \"contracts/**/*.sol\"", "lint:sol:fix": "solhint --max-warnings 0 \"contracts/**/*.sol\" --fix", "test": "hardhat test" - } + }, + "bugs": { + "url": "https://github.com/1inch/1inch-solidity-utils/issues" + }, + "homepage": "https://github.com/1inch/1inch-solidity-utils#readme", + "directories": { + "test": "test" + }, + "author": "1inch", + "description": "" } diff --git a/utils/docify.utils.js b/utils/docify.utils.js new file mode 100644 index 00000000..0719e9ce --- /dev/null +++ b/utils/docify.utils.js @@ -0,0 +1,118 @@ +const SOLC_NPM_NAME = 'solc'; +const BASE_DIR = 'docgen'; +const SCRIPT_DIR = __dirname; +const INPUT_DIR = 'contracts'; +const OUTPUT_DIR = `${BASE_DIR}/docs`; +const HELPERS_PATH = `${SCRIPT_DIR}/solidity-docgen-helpers.js`; + +const fs = require('fs'); +const path = require('path'); +const spawn = require('cross-spawn'); + +function getFileNameWithoutExtension(fileName) { + return fileName.substr(0, fileName.lastIndexOf(".")); +} + +function runProcess(name, args) { + console.log(`running ${name} with args ${JSON.stringify(args)}`); + const result = spawn.sync(name, args, {stdio: ['inherit', 'inherit', 'pipe']}); + if (result.stderr.length > 0) { + throw new Error(result.stderr); + } +} + +function getReadmes(targetPath) { + let result = []; + const readmePath = path.join(targetPath, 'README.md'); + if (!fs.existsSync(readmePath)) { + const content = `# ${path.basename(targetPath)}\n`; + result.push({path: readmePath, content}); + } + const childDirs = fs.readdirSync(targetPath, {withFileTypes: true}).filter(item => item.isDirectory()); + for (let dir of childDirs) { + result = result.concat(getReadmes(path.join(targetPath, dir.name))); + } + return result; +} + +function generateReadmes(readmes) { + for (let readme of readmes) { + fs.writeFileSync(readme.path, readme.content); + } +} + +function getSummary(targetPath) { + function getSummaryRoot(summaryTargetPath, indentation) { + function specialCaseRoot(item) { + if (item.indentation >= 0) { + return item; + } + return ({ + name: "Main Readme", + path: item.path, + indentation: 0 + }); + } + + const items = fs.readdirSync(summaryTargetPath, {withFileTypes: true}); + let result = [specialCaseRoot({ + name: path.basename(summaryTargetPath), + path: path.relative(targetPath, path.join(summaryTargetPath, 'README.md')).replaceAll('\\', '/'), + indentation: indentation - 1 + })]; + for (let dir of items.filter(item => item.isDirectory())) { + result = result.concat(getSummaryRoot(path.join(summaryTargetPath, dir.name), indentation + 1)); + } + result = result + .concat(items + .filter(item => !item.isDirectory() + && !item.name.endsWith('README.md') + && !item.name.endsWith('SUMMARY.md')) + .map(file => ({ + name: getFileNameWithoutExtension(file.name), + path: path.relative(targetPath, path.join(summaryTargetPath, file.name)).replaceAll('\\', '/'), + indentation + }))); + return result; + } + + function generateContent(summaryTree) { + const lines = summaryTree.map(x => `${' '.repeat(x.indentation)}* [${x.name}](${x.path})`).join('\n'); + return `# Table of contents\n\n${lines}`; + } + + return generateContent(getSummaryRoot(targetPath, 0)); +} + +function generateSummary(targetPath, summary) { + fs.writeFileSync(path.join(targetPath, "SUMMARY.md"), summary); +} + +function generateGitbookFiles() { + fs.copyFileSync(path.join(BASE_DIR, 'README.md'), path.join(OUTPUT_DIR, 'README.md')); + const readmesToGenerate = getReadmes(OUTPUT_DIR); + const summary = getSummary(OUTPUT_DIR); + + generateReadmes(readmesToGenerate); + generateSummary(OUTPUT_DIR, summary); +} + +const solidityDocgenArgs = [ + 'solidity-docgen', + '-i', + INPUT_DIR, + '-o', + OUTPUT_DIR, + '--solc-module', + SOLC_NPM_NAME, + '--solc-settings', + JSON.stringify({optimizer: {enabled: false}}), + '--templates', + SCRIPT_DIR, + '--helpers', + HELPERS_PATH, +]; + +fs.rmSync(OUTPUT_DIR, {force: true, recursive: true}); +runProcess('npx', solidityDocgenArgs); +generateGitbookFiles(); diff --git a/yarn.lock b/yarn.lock index 166dff07..817e9742 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2382,7 +2382,7 @@ cross-spawn@^6.0.0, cross-spawn@^6.0.5: shebang-command "^1.2.0" which "^1.2.9" -cross-spawn@^7.0.2: +cross-spawn@^7.0.2, cross-spawn@^7.0.3: version "7.0.3" resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.3.tgz#f73a85b9d5d41d045551c177e2882d4ac85728a6" integrity sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==