From 6200ceddf8c66eeca15a9ac01359d45cea9e96d8 Mon Sep 17 00:00:00 2001 From: Henry Date: Fri, 11 Dec 2015 09:51:58 -0800 Subject: [PATCH 1/4] [Documentation] Add text to main page #228 --- docs/gendocs.js | 19 +++++++++++++------ docs/src/index.html | 38 -------------------------------------- docs/src/index.md | 35 +++++++++++++++++++++++++++++++++++ package.json | 2 +- 4 files changed, 49 insertions(+), 45 deletions(-) delete mode 100644 docs/src/index.html create mode 100644 docs/src/index.md diff --git a/docs/gendocs.js b/docs/gendocs.js index 51c84d9a64..8ec401e0c3 100644 --- a/docs/gendocs.js +++ b/docs/gendocs.js @@ -106,7 +106,7 @@ GLOBAL.window = GLOBAL.window || GLOBAL; // nomnoml expects window to be define } // Convert from Github-flavored Markdown to HTML - function gfmifier() { + function gfmifier(renderTOC) { var transform = new stream.Transform({ objectMode: true }), markdown = ""; transform._transform = function (chunk, encoding, done) { @@ -114,9 +114,11 @@ GLOBAL.window = GLOBAL.window || GLOBAL; // nomnoml expects window to be define done(); }; transform._flush = function (done) { - // Prepend table of contents - markdown = - [ TOC_HEAD, toc(markdown).content, "", markdown ].join("\n"); + if (renderTOC){ + // Prepend table of contents + markdown = + [ TOC_HEAD, toc(markdown).content, "", markdown ].join("\n"); + } this.push(header); this.push(marked(markdown)); this.push(footer); @@ -146,6 +148,10 @@ GLOBAL.window = GLOBAL.window || GLOBAL; // nomnoml expects window to be define return customRenderer; } + function matchesPattern(pattern, candidate){ + return candidate.match(pattern); + } + options['in'] = options['in'] || options.i; options.out = options.out || options.o; @@ -168,13 +174,14 @@ GLOBAL.window = GLOBAL.window || GLOBAL; // nomnoml expects window to be define var destination = file.replace(options['in'], options.out) .replace(/md$/, "html"), destPath = path.dirname(destination), - prefix = path.basename(destination).replace(/\.html$/, ""); + prefix = path.basename(destination).replace(/\.html$/, ""), + renderTOC = file.match(options['suppress-toc'] || "") === null; mkdirp(destPath, function (err) { fs.createReadStream(file, { encoding: 'utf8' }) .pipe(split()) .pipe(nomnomlifier(destPath, prefix)) - .pipe(gfmifier()) + .pipe(gfmifier(renderTOC)) .pipe(fs.createWriteStream(destination, { encoding: 'utf8' })); diff --git a/docs/src/index.html b/docs/src/index.html deleted file mode 100644 index 727523eda3..0000000000 --- a/docs/src/index.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - Open MCT Web Documentation - - - Sections: - - - diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000000..3bf957156f --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,35 @@ +# OpenMCTWeb Documentation + +## Overview + + Documentation is provided to support the use and development of the + OpenMCTWeb mission operations software. It's recommended that before doing + any development with OpenMCTWeb you take some time to familiarize yourself + with the documentation below. + + OpenMCTWeb provides functionality out of the box, but it's also a framework for + building rich mission operations applications based on modern web technology. + The framework is configured declaratively, and defines conventions for + building on the provided capabilities by creating modular 'bundles' that + extend the provided extension points. The details of how to extend the + framework are provided in the following documentation. + +## Sections + + * The [Architecture Overview](architecture/) describes the concepts used + throughout OpenMCTWeb, and gives a high level overview of the framework's design. + + * The [Developer's guide](guide/) goes into more detail about how to use the + framework + and the capabilities that it provides. + + * The [Tutorials](tutorials/) give examples of extending the platform to add + functionality, + and integrate with data sources. + + * The [API](api/) document is generated from inline documentation + using jsdoc, and describes the javascript objects and functions that make up + the software framework. + + * Finally, the [Development Process](process/) document describes the + OpenMCTWeb software development cycle. \ No newline at end of file diff --git a/package.json b/package.json index c96642129c..e753aa7bfb 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,7 @@ "jshint": "jshint platform example || exit 0", "watch": "karma start", "jsdoc": "jsdoc -c jsdoc.json -r -d target/docs/api", - "otherdoc": "node docs/gendocs.js --in docs/src --out target/docs", + "otherdoc": "node docs/gendocs.js --in docs/src --out target/docs --suppress-toc 'docs/src/index.md|docs/src/process/index.md'", "docs": "npm run jsdoc ; npm run otherdoc" }, "repository": { From 604b29096d760f4c19bfe6163548a4f3c3b148d3 Mon Sep 17 00:00:00 2001 From: Henry Date: Fri, 11 Dec 2015 09:53:55 -0800 Subject: [PATCH 2/4] [Documentation] #228 added inline comment about TOC suppression --- docs/gendocs.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/gendocs.js b/docs/gendocs.js index 8ec401e0c3..f01db5b340 100644 --- a/docs/gendocs.js +++ b/docs/gendocs.js @@ -175,6 +175,8 @@ GLOBAL.window = GLOBAL.window || GLOBAL; // nomnoml expects window to be define .replace(/md$/, "html"), destPath = path.dirname(destination), prefix = path.basename(destination).replace(/\.html$/, ""), + //Determine whether TOC should be rendered for this file based + //on regex provided as command line option renderTOC = file.match(options['suppress-toc'] || "") === null; mkdirp(destPath, function (err) { From b6acdb12ec532acaa2ca1ca2a157d52a3be6b324 Mon Sep 17 00:00:00 2001 From: Henry Date: Fri, 11 Dec 2015 11:09:03 -0800 Subject: [PATCH 3/4] Removed superfluous function --- docs/gendocs.js | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/gendocs.js b/docs/gendocs.js index f01db5b340..10facc0ded 100644 --- a/docs/gendocs.js +++ b/docs/gendocs.js @@ -148,10 +148,6 @@ GLOBAL.window = GLOBAL.window || GLOBAL; // nomnoml expects window to be define return customRenderer; } - function matchesPattern(pattern, candidate){ - return candidate.match(pattern); - } - options['in'] = options['in'] || options.i; options.out = options.out || options.o; From 0d894a9f39cc1583409c196a0af192cb61e14840 Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Fri, 11 Dec 2015 11:54:23 -0800 Subject: [PATCH 4/4] [Documentation] Tweak spelling / phrasing * Add spaces to 'Open MCT Web' for consistency * Use term 'platform' instead of 'framework' for consistency with the developer guide * Avoid the term 'capabilities' (could be ambiguous in the context of other documentation) * Use canonical casing for JSDoc and JavaScript * Simplify phrasing of first sentence * Change casing of 'Developer Guide' for consistency with other bullets From review of https://github.com/nasa/openmctweb/pull/412 --- docs/src/index.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/src/index.md b/docs/src/index.md index 3bf957156f..dbb1d36220 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,35 +1,35 @@ -# OpenMCTWeb Documentation +# Open MCT Web Documentation ## Overview - Documentation is provided to support the use and development of the - OpenMCTWeb mission operations software. It's recommended that before doing - any development with OpenMCTWeb you take some time to familiarize yourself + Documentation is provided to support the use and development of + Open MCT Web. It's recommended that before doing + any development with Open MCT Web you take some time to familiarize yourself with the documentation below. - OpenMCTWeb provides functionality out of the box, but it's also a framework for + Open MCT Web provides functionality out of the box, but it's also a platform for building rich mission operations applications based on modern web technology. - The framework is configured declaratively, and defines conventions for + The platform is configured declaratively, and defines conventions for building on the provided capabilities by creating modular 'bundles' that - extend the provided extension points. The details of how to extend the - framework are provided in the following documentation. + extend the platform at a variety of extension points. The details of how to + extend the platform are provided in the following documentation. ## Sections * The [Architecture Overview](architecture/) describes the concepts used - throughout OpenMCTWeb, and gives a high level overview of the framework's design. + throughout Open MCT Web, and gives a high level overview of the platform's design. - * The [Developer's guide](guide/) goes into more detail about how to use the - framework - and the capabilities that it provides. + * The [Developer's Guide](guide/) goes into more detail about how to use the + platform and the functionality that it provides. * The [Tutorials](tutorials/) give examples of extending the platform to add functionality, and integrate with data sources. * The [API](api/) document is generated from inline documentation - using jsdoc, and describes the javascript objects and functions that make up - the software framework. + using [JSDoc](http://usejsdoc.org/), and describes the JavaScript objects and + functions that make up the software platform. * Finally, the [Development Process](process/) document describes the - OpenMCTWeb software development cycle. \ No newline at end of file + Open MCT Web software development cycle. + \ No newline at end of file