feat: add sol-doc command-line interface

modified sol-compiler to output progress/warning/error/etc messages to
stderr rather than stdout, so that sol-doc can put its output (and
nothing else) to stdout.

for posterity, added sol-doc cli usage as npm scripts to package.json.

packages/sol-compiler/src/compiler.ts

@@ -94,7 +94,7 @@ export class Compiler {
         if (await fsWrapper.doesFileExistAsync(compilerBinFilename)) {
             solcjs = (await fsWrapper.readFileAsync(compilerBinFilename)).toString();
         } else {
-            logUtils.log(`Downloading ${fullSolcVersion}...`);
+            logUtils.warn(`Downloading ${fullSolcVersion}...`);
             const url = `${constants.BASE_COMPILER_URL}${fullSolcVersion}`;
             const response = await fetchAsync(url);
             const SUCCESS_STATUS = 200;
@@ -181,7 +181,9 @@ export class Compiler {
                 path.basename(contractSource.path, constants.SOLIDITY_FILE_EXTENSION),
             );
         } else {
-            contractNamesToCompile = this._specifiedContracts;
+            contractNamesToCompile = this._specifiedContracts.map(specifiedContract =>
+                path.basename(specifiedContract, constants.SOLIDITY_FILE_EXTENSION),
+            );
         }
         return contractNamesToCompile;
     }
@@ -236,7 +238,7 @@ export class Compiler {
         const solcVersions = _.keys(versionToInputs);
         for (const solcVersion of solcVersions) {
             const input = versionToInputs[solcVersion];
-            logUtils.log(
+            logUtils.warn(
                 `Compiling ${input.contractsToCompile.length} contracts (${
                     input.contractsToCompile
                 }) with Solidity v${solcVersion}...`,
@@ -329,7 +331,7 @@ export class Compiler {
         const artifactString = utils.stringifyWithFormatting(newArtifact);
         const currentArtifactPath = `${this._artifactsDir}/${contractName}.json`;
         await fsWrapper.writeFileAsync(currentArtifactPath, artifactString);
-        logUtils.log(`${contractName} artifact saved!`);
+        logUtils.warn(`${contractName} artifact saved!`);
     }
     private _compile(solcInstance: solc.SolcInstance, standardInput: solc.StandardInput): solc.StandardOutput {
         const compiled: solc.StandardOutput = JSON.parse(
@@ -345,13 +347,13 @@ export class Compiler {
             if (!_.isEmpty(errors)) {
                 errors.forEach(error => {
                     const normalizedErrMsg = getNormalizedErrMsg(error.formattedMessage || error.message);
-                    logUtils.log(chalk.red(normalizedErrMsg));
+                    logUtils.warn(chalk.red(normalizedErrMsg));
                 });
                 throw new Error('Compilation errors encountered');
             } else {
                 warnings.forEach(warning => {
                     const normalizedWarningMsg = getNormalizedErrMsg(warning.formattedMessage || warning.message);
-                    logUtils.log(chalk.yellow(normalizedWarningMsg));
+                    logUtils.warn(chalk.yellow(normalizedWarningMsg));
                 });
             }
         }

packages/sol-compiler/src/utils/compiler.ts

@@ -26,7 +26,7 @@ export async function getContractArtifactIfExistsAsync(
         contractArtifact = JSON.parse(contractArtifactString);
         return contractArtifact;
     } catch (err) {
-        logUtils.log(`Artifact for ${contractName} does not exist`);
+        logUtils.warn(`Artifact for ${contractName} does not exist`);
         return undefined;
     }
 }
@@ -37,7 +37,7 @@ export async function getContractArtifactIfExistsAsync(
  */
 export async function createDirIfDoesNotExistAsync(dirPath: string): Promise<void> {
     if (!fsWrapper.doesPathExistSync(dirPath)) {
-        logUtils.log(`Creating directory at ${dirPath}...`);
+        logUtils.warn(`Creating directory at ${dirPath}...`);
         await fsWrapper.mkdirpAsync(dirPath);
     }
 }

packages/sol-doc/package.json

@@ -11,7 +11,12 @@
         "test:coverage": "nyc npm run test --all && yarn coverage:report:lcov",
         "coverage:report:lcov": "nyc report --reporter=text-lcov > coverage/lcov.info",
         "lint": "tslint --project . --format stylish",
-        "clean": "shx rm -rf lib"
+        "clean": "shx rm -rf lib",
+        "generate-v2-protocol-docs": "(cd ../contracts/src/2.0.0; node ../../../../node_modules/.bin/sol-doc --contracts-dir . --contracts $(cd protocol; ls -C1 */*.sol */interfaces/*.sol) ) > v2.0.0.json",
+        "deploy-v2-protocol-docs": "aws --profile 0xproject s3 cp --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json v2.0.0.json s3://staging-doc-jsons/contracts/"
+    },
+    "bin": {
+        "sol-doc": "bin/sol-doc.js"
     },
     "repository": "https://github.com/0xProject/0x-monorepo.git",
     "author": "F. Eugene Aumson",
@@ -21,7 +26,8 @@
         "@0xproject/types": "^1.0.1-rc.6",
         "@0xproject/utils": "^1.0.5",
         "ethereum-types": "^1.0.4",
-        "lodash": "^4.17.10"
+        "lodash": "^4.17.10",
+        "yargs": "^12.0.2"
     },
     "devDependencies": {
         "@0xproject/tslint-config": "^1.0.6",

packages/sol-doc/src/cli.ts

@@ -0,0 +1,26 @@
+import 'source-map-support/register';
+import * as yargs from 'yargs';
+
+import { generateSolDocAsync } from './solidity_doc_generator';
+
+const JSON_TABWIDTH = 4;
+
+(async () => {
+    const argv = yargs
+        .option('contracts-dir', {
+            type: 'string',
+            description: 'path of contracts directory to compile',
+        })
+        .option('contracts', {
+            type: 'string',
+            description: 'comma separated list of contracts to compile',
+        })
+        .demandOption('contracts-dir')
+        .array('contracts')
+        .help().argv;
+    process.stdout.write(
+        JSON.stringify(await generateSolDocAsync(argv.contractsDir, argv.contracts), null, JSON_TABWIDTH),
+    );
+})().catch(err => {
+    throw err;
+});