diff --git a/README.md b/README.md index f4cb9a82..447dbbe7 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,36 @@ and run it like a normal npm script : npm run compodoc ``` +### Common use cases + +#### Render documentation + +Documentation is generated in default output folder, then run your HTTP server in that folder. + +``` +compodoc -p src/tsconfig.json +``` + +#### Serve generated documentation with compodoc + +Documentation was generated in default output folder or a specific one, the local HTTP server is launched at [http://localhost:8080](http://localhost:8080) + +``` +compodoc -s + +or + +compodoc -s -d ./doc +``` + +#### Render documentation, and serve it with compodoc + +Documentation is generated in default output folder, and a local HTTP server is available at [http://localhost:8080](http://localhost:8080) + +``` +compodoc -p src/tsconfig.json -s +``` + ### Remark for routes Follow the style guide and provide a const of type 'Routes' : diff --git a/src/app/application.ts b/src/app/application.ts index 99e40530..a7cd2f3d 100644 --- a/src/app/application.ts +++ b/src/app/application.ts @@ -27,12 +27,13 @@ let pkg = require('../package.json'), export namespace Application { - let defaultTitle = `Application documentation`; + let defaultTitle = `Application documentation`, + defaultFolder = `./documentation/`; program .version(pkg.version) .option('-p, --tsconfig [config]', 'A tsconfig.json file') - .option('-d, --output [folder]', 'Where to store the generated documentation (default: ./documentation)', `./documentation/`) + .option('-d, --output [folder]', 'Where to store the generated documentation (default: ./documentation)') .option('-b, --base [base]', 'Base reference of html tag ', '/') .option('-n, --name [name]', 'Title documentation', defaultTitle) .option('-o, --open', 'Open the generated documentation', false) @@ -50,6 +51,10 @@ export namespace Application { logger.silent = false; } + if (program.output) { + defaultFolder = program.output; + } + $configuration.mainData.documentationMainName = program.name; //default commander value $configuration.mainData.base = program.base; @@ -293,7 +298,7 @@ export namespace Application { if( i <= len-1) { logger.info('Process page', pages[i].name); $htmlengine.render($configuration.mainData, pages[i]).then((htmlData) => { - let path = program.output; + let path = defaultFolder; if (pages[i].path) { path += '/' + pages[i].path + '/'; } @@ -318,7 +323,7 @@ export namespace Application { let processResources = () => { logger.info('Copy main resources'); - fs.copy(path.resolve(__dirname + '/../src/resources/'), path.resolve(process.cwd() + path.sep + program.output), function (err) { + fs.copy(path.resolve(__dirname + '/../src/resources/'), path.resolve(process.cwd() + path.sep + defaultFolder), function (err) { if (err) { logger.error('Error during resources copy'); } else { @@ -343,7 +348,11 @@ export namespace Application { }); } else { let finalTime = (new Date() - startTime) / 1000; - logger.info('Documentation generated in ' + program.output + 'in ' + finalTime + ' seconds'); + logger.info('Documentation generated in ' + defaultFolder + ' in ' + finalTime + ' seconds'); + if (program.serve) { + logger.info(`Serving documentation from ${defaultFolder} at http://127.0.0.1:8080`); + runWebServer(defaultFolder); + } } }; $ngdengine.renderGraph(program.tsconfig, 'documentation/graph', 'p').then(() => { @@ -353,75 +362,94 @@ export namespace Application { }); } + let runWebServer = (folder) => { + LiveServer.start({ + root: folder, + open: false, + quiet: true, + logLevel: 0 + }); + } + export let run = () => { let _file; - if (program.serve) { - logger.info('Serving documentation at http://127.0.0.1:8080'); - LiveServer.start({ - root: program.output, - open: false, - quiet: true, - logLevel: 0 - }); - } - - if (program.hideGenerator) { - $configuration.mainData.hideGenerator = true; - } - - if (program.tsconfig) { - if (!fs.existsSync(program.tsconfig)) { - logger.fatal('"tsconfig.json" file was not found in the current directory'); + if (program.serve && !program.tsconfig && program.output) { + // if -s & -d, serve it + if (!fs.existsSync(program.output)) { + logger.fatal(`${program.output} folder doesn't exist`); process.exit(1); } else { - _file = path.join( - path.join(process.cwd(), path.dirname(program.tsconfig)), - path.basename(program.tsconfig) - ); - logger.info('Using tsconfig', _file); - - files = require(_file).files; - - // use the current directory of tsconfig.json as a working directory - cwd = _file.split(path.sep).slice(0, -1).join(path.sep); - - if (!files) { - let exclude = require(_file).exclude || []; - - var walk = (dir) => { - let results = []; - let list = fs.readdirSync(dir); - list.forEach((file) => { - if (exclude.indexOf(file) < 0) { - file = path.join(dir, file); - let stat = fs.statSync(file); - if (stat && stat.isDirectory()) { - results = results.concat(walk(file)); - } - else if (/(spec|\.d)\.ts/.test(file)) { - logger.debug('Ignoring', file); - } - else if (path.extname(file) === '.ts') { - logger.debug('Including', file); - results.push(file); + logger.info(`Serving documentation from ${program.output} at http://127.0.0.1:8080`); + runWebServer(program.output); + } + } else if (program.serve && !program.tsconfig && !program.output) { + // if only -s find ./documentation, if ok serve, else error provide -d + if (!fs.existsSync(defaultFolder)) { + logger.fatal('Provide output generated folder with -d flag'); + process.exit(1); + } else { + logger.info(`Serving documentation from ${defaultFolder} at http://127.0.0.1:8080`); + runWebServer(defaultFolder); + } + } else { + if (program.hideGenerator) { + $configuration.mainData.hideGenerator = true; + } + + if (program.tsconfig) { + if (!fs.existsSync(program.tsconfig)) { + logger.fatal('"tsconfig.json" file was not found in the current directory'); + process.exit(1); + } else { + _file = path.join( + path.join(process.cwd(), path.dirname(program.tsconfig)), + path.basename(program.tsconfig) + ); + logger.info('Using tsconfig', _file); + + files = require(_file).files; + + // use the current directory of tsconfig.json as a working directory + cwd = _file.split(path.sep).slice(0, -1).join(path.sep); + + if (!files) { + let exclude = require(_file).exclude || []; + + var walk = (dir) => { + let results = []; + let list = fs.readdirSync(dir); + list.forEach((file) => { + if (exclude.indexOf(file) < 0) { + file = path.join(dir, file); + let stat = fs.statSync(file); + if (stat && stat.isDirectory()) { + results = results.concat(walk(file)); + } + else if (/(spec|\.d)\.ts/.test(file)) { + logger.debug('Ignoring', file); + } + else if (path.extname(file) === '.ts') { + logger.debug('Including', file); + results.push(file); + } } - } - }); - return results; - }; + }); + return results; + }; - files = walk(cwd || '.'); - } + files = walk(cwd || '.'); + } - $htmlengine.init().then(() => { - processPackageJson(); - }); + $htmlengine.init().then(() => { + processPackageJson(); + }); + } + } else { + logger.fatal('Entry file was not found'); + outputHelp(); } - } else { - logger.fatal('Entry file was not found'); - outputHelp(); } } }