You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by dblotsky <gi...@git.apache.org> on 2016/04/20 04:16:24 UTC
[GitHub] cordova-docs pull request: ToC Generation Refactor
GitHub user dblotsky opened a pull request:
https://github.com/apache/cordova-docs/pull/583
ToC Generation Refactor
**Note**: this PR is easier to review one commit at a time, and the commit messages roughly describe each change.
Changes:
- now `*-src.yml` files are mandatory for each docs version
- `*-src.yml` files get turned into `*-gen.yml` files
- renamed `*-manual.yml` files to the new `*-src.yml` format
- ToCs now contain only entries with `uri`s (unless they have children)
- pages now specify their ToC name using the `title` or `toc_title` front matter property
- removed the `name` property from ToC entries, moving it to the respective page where necessary
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/MSOpenTech/cordova-docs toc-gen-refactor
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/cordova-docs/pull/583.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #583
----
commit 7022ab8713517e99904fbe0a33ac02aa0a637dc0
Author: Dmitry Blotsky <dm...@gmail.com>
Date: 2016-04-20T01:45:44Z
Refactoring ToC generation process: source ToCs are always required, and the result ToCs are generated from them. Refactoring Makefile for better readability.
commit 297128f29dabf2afc7b9c620b048d589029f02f6
Author: Dmitry Blotsky <dm...@gmail.com>
Date: 2016-04-20T01:53:43Z
Renamed ToCs to match new ToC build process.
commit 7b879387a81617b8a783e58398f84aefb1b9a181
Author: Dmitry Blotsky <dm...@gmail.com>
Date: 2016-04-20T02:05:57Z
Moving ToC names into toc_title properties for their respective files, and also removing the 'name' property from all ToC files.
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: ToC Generation Refactor
Posted by dblotsky <gi...@git.apache.org>.
Github user dblotsky commented on the pull request:
https://github.com/apache/cordova-docs/pull/583#issuecomment-212213980
@riknoll @rakatyal @nikhilkh please review when you have a moment.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: ToC Generation Refactor
Posted by dblotsky <gi...@git.apache.org>.
Github user dblotsky commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/583#discussion_r60496008
--- Diff: tools/bin/toc.js ---
@@ -17,123 +17,57 @@
"use strict";
-var fs = require("fs");
-var path = require("path");
+var fs = require("fs");
+var path = require("path");
+var childProcess = require("child_process");
+
var yaml = require("js-yaml");
-var walk = require("walk");
var Q = require("q");
var argv = require("optimist").argv;
-var util = require("./util");
-
-function isUnderline(line) {
- return /-+|=+|\*+/.test(line);
-}
-
-function getPageTitle(filePath) {
- var file = fs.readFileSync(filePath, 'utf8');
- var res = /<h1>([^<]*)<\/h1>|#\ (.*)|(.*)[\n\f\r]+(?:={3}=+|-{3}-+)/.exec(file);
- if (res) {
- if (res[1]) {
- return res[1].trim();
- }
- if (res[2]) {
- return res[2].trim();
- }
- if (res[3]) {
- return res[3].trim();
- }
- }
- return null;
-}
-
-function generateToC(sourceDir) {
-
- var deferred = Q.defer();
- var toc = [];
-
- // go through each file in sourceDir
- var walker = walk.walk(sourceDir);
- walker.on("file", function (dirPrefix, fileStats, next) {
-
- var fileName = fileStats.name;
- var filePath = path.join(dirPrefix, fileName);
-
- // get the page path
- var pagePrefix = dirPrefix.replace(sourceDir, '');
- var pagePath = path.join(pagePrefix, fileName);
- var pageURI = pagePath.replace(".md", ".html").replace(/\\/g, "/");
-
- // remove leading slash
- if (pageURI[0] === "/") {
- pageURI = pageURI.substr(1);
- }
-
- // get heading
- var heading = getPageTitle(filePath);
-
- // if the page has a heading, add it to the ToC
- if (heading) {
- toc.push({
- name: heading,
- url: pageURI
- });
- }
-
- next();
- });
-
- walker.on("errors", function (root, nodeStatsArray, next) {
- console.error("ERROR while processing " + root);
- next();
- });
-
- walker.on("end", function () {
- deferred.resolve(toc);
- });
-
- return deferred.promise;
-}
+var augment = require("./augment_toc");
+var util = require("./util");
function main () {
var docsRoot = argv._[0];
- var dataRoot = argv._[1];
+ var tocRoot = argv._[1];
// validate args
- if ((!docsRoot) || (!dataRoot)) {
+ if ((!docsRoot) || (!tocRoot)) {
var scriptName = path.basename(process.argv[1]);
- console.log("usage: " + scriptName + " docsRoot dataRoot");
+ console.log("usage: " + scriptName + " docsRoot tocRoot");
console.log(scriptName + ": error: too few arguments");
return 1;
}
- var tocRoot = path.join(dataRoot, 'toc');
-
// go through all the languages
util.listdirsSync(docsRoot).forEach(function (languageName) {
-
var languagePath = path.join(docsRoot, languageName);
// go through all the versions
util.listdirsSync(languagePath).forEach(function (versionName) {
-
var versionPath = path.join(languagePath, versionName);
- var outputName = util.generatedTocfileName(languageName, versionName);
- var outputPath = path.join(tocRoot, outputName);
- // generate ToC
- generateToC(versionPath).then(function (toc) {
+ var srcTocName = util.srcTocfileName(languageName, versionName);
+ var destTocName = util.genTocfileName(languageName, versionName);
- // sort the ToC
- toc.sort(function (a, b) {
- return a.name.localeCompare(b.name, languageName);
- });
+ var srcTocPath = path.join(tocRoot, srcTocName);
+ var destTocPath = path.join(tocRoot, destTocName);
- // save it to a file
- var tocText = yaml.dump(toc);
- console.log(outputPath);
- fs.writeFileSync(outputPath, tocText, 'utf8');
+ // read the input
+ fs.readFile(srcTocPath, function (error, data) {
+
+ // augment the ToC
+ var originalTocString = data.toString();
+ var augmentedTocString = augment.augmentString(originalTocString, versionPath);
+ var warningComment = console.log(util.generatedBy(__filename));
+ var output = warningComment + "\n" + augmentedTocString;
--- End diff --
Good catch! Fixed.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: ToC Generation Refactor
Posted by riknoll <gi...@git.apache.org>.
Github user riknoll commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/583#discussion_r60495374
--- Diff: tools/bin/toc.js ---
@@ -17,123 +17,57 @@
"use strict";
-var fs = require("fs");
-var path = require("path");
+var fs = require("fs");
+var path = require("path");
+var childProcess = require("child_process");
+
var yaml = require("js-yaml");
-var walk = require("walk");
var Q = require("q");
var argv = require("optimist").argv;
-var util = require("./util");
-
-function isUnderline(line) {
- return /-+|=+|\*+/.test(line);
-}
-
-function getPageTitle(filePath) {
- var file = fs.readFileSync(filePath, 'utf8');
- var res = /<h1>([^<]*)<\/h1>|#\ (.*)|(.*)[\n\f\r]+(?:={3}=+|-{3}-+)/.exec(file);
- if (res) {
- if (res[1]) {
- return res[1].trim();
- }
- if (res[2]) {
- return res[2].trim();
- }
- if (res[3]) {
- return res[3].trim();
- }
- }
- return null;
-}
-
-function generateToC(sourceDir) {
-
- var deferred = Q.defer();
- var toc = [];
-
- // go through each file in sourceDir
- var walker = walk.walk(sourceDir);
- walker.on("file", function (dirPrefix, fileStats, next) {
-
- var fileName = fileStats.name;
- var filePath = path.join(dirPrefix, fileName);
-
- // get the page path
- var pagePrefix = dirPrefix.replace(sourceDir, '');
- var pagePath = path.join(pagePrefix, fileName);
- var pageURI = pagePath.replace(".md", ".html").replace(/\\/g, "/");
-
- // remove leading slash
- if (pageURI[0] === "/") {
- pageURI = pageURI.substr(1);
- }
-
- // get heading
- var heading = getPageTitle(filePath);
-
- // if the page has a heading, add it to the ToC
- if (heading) {
- toc.push({
- name: heading,
- url: pageURI
- });
- }
-
- next();
- });
-
- walker.on("errors", function (root, nodeStatsArray, next) {
- console.error("ERROR while processing " + root);
- next();
- });
-
- walker.on("end", function () {
- deferred.resolve(toc);
- });
-
- return deferred.promise;
-}
+var augment = require("./augment_toc");
+var util = require("./util");
function main () {
var docsRoot = argv._[0];
- var dataRoot = argv._[1];
+ var tocRoot = argv._[1];
// validate args
- if ((!docsRoot) || (!dataRoot)) {
+ if ((!docsRoot) || (!tocRoot)) {
var scriptName = path.basename(process.argv[1]);
- console.log("usage: " + scriptName + " docsRoot dataRoot");
+ console.log("usage: " + scriptName + " docsRoot tocRoot");
console.log(scriptName + ": error: too few arguments");
return 1;
}
- var tocRoot = path.join(dataRoot, 'toc');
-
// go through all the languages
util.listdirsSync(docsRoot).forEach(function (languageName) {
-
var languagePath = path.join(docsRoot, languageName);
// go through all the versions
util.listdirsSync(languagePath).forEach(function (versionName) {
-
var versionPath = path.join(languagePath, versionName);
- var outputName = util.generatedTocfileName(languageName, versionName);
- var outputPath = path.join(tocRoot, outputName);
- // generate ToC
- generateToC(versionPath).then(function (toc) {
+ var srcTocName = util.srcTocfileName(languageName, versionName);
+ var destTocName = util.genTocfileName(languageName, versionName);
- // sort the ToC
- toc.sort(function (a, b) {
- return a.name.localeCompare(b.name, languageName);
- });
+ var srcTocPath = path.join(tocRoot, srcTocName);
+ var destTocPath = path.join(tocRoot, destTocName);
- // save it to a file
- var tocText = yaml.dump(toc);
- console.log(outputPath);
- fs.writeFileSync(outputPath, tocText, 'utf8');
+ // read the input
+ fs.readFile(srcTocPath, function (error, data) {
+
+ // augment the ToC
+ var originalTocString = data.toString();
+ var augmentedTocString = augment.augmentString(originalTocString, versionPath);
+ var warningComment = console.log(util.generatedBy(__filename));
+ var output = warningComment + "\n" + augmentedTocString;
--- End diff --
This should just be the string and not console.log
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: CB-11126 ToC Generation Refactor
Posted by dblotsky <gi...@git.apache.org>.
Github user dblotsky closed the pull request at:
https://github.com/apache/cordova-docs/pull/583
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: ToC Generation Refactor
Posted by riknoll <gi...@git.apache.org>.
Github user riknoll commented on the pull request:
https://github.com/apache/cordova-docs/pull/583#issuecomment-212648942
LGTM
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org