Update docs/contracts/README.md and cli.js to take that into account (#308)

Author: tsuberim

docs/contracts/README.md

@@ -1,8 +1,7 @@
-Welcome to the generated documentation!
+Welcome to contracts documentation!
 
-This directory contains automated documentation generated directly from `.sol` source files.
-They include the following info:
+This directory includes manual markdown documentation for `contracts` directory.
+It follows the directory structure of `contracts` (eg. file `foo/bar.md` documents the `bar` contract in `contracts/foo`).
 
-- Gas estimates on constructors & functions.
-- Technical information about the exposed public interface of each contract.
-- A manual documentation snippet at the top, if available.
+Files in this folder will be included in `../generated_docs` (with `yarn docs update`) and merged with automatically generated docs (if available) based on their file name.
+*Example: `foo/bar.md` will be merged with automated docs for the contract `bar` in the directory `contracts/foo/`*

scripts/docs/cli.js

@@ -85,9 +85,13 @@ const clean = (argv,code = 0) => {
  */
 const update = (argv) => {
     try{
+        // keep `${argv.output}/README.md`, as we don't want to override it with `${argv.headers}/README.md`
+        const readme = fs.readFileSync(`${argv.output}/README.md`,'utf-8');
         shell.rm('-rf',argv.output);
         shell.mkdir(argv.output);
         shell.cp('-rf',argv.headers+'/*',argv.output);
+        // restore `${argv.output}/README.md`
+        fs.writeFileSync(`${argv.output}/README.md`,readme,'utf-8');
         const files = shell.find(argv.input).filter(x => path.extname(x) === '.sol');
         print(`Compiling ${files.length} files from ${argv.input} ...`);
         const output = compile(files);