From 224012a51dad139c10033f7f01137188842894d8 Mon Sep 17 00:00:00 2001 From: Stephen Belanger Date: Sun, 24 Jan 2016 22:17:50 -0800 Subject: [PATCH 1/2] doc: support generating guide docs This adds a new html-guides format to the current doctool. It's kind of a hack. I'll make it better, promise. --- Makefile | 21 ++++++++++++++++++++- doc/guides/test.md | 1 + tools/doc/generate.js | 8 ++++++++ tools/doc/guides.js | 10 ++++++++++ 4 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 doc/guides/test.md create mode 100644 tools/doc/guides.js diff --git a/Makefile b/Makefile index 5bfb80119c3951..4aa256bde8a8f7 100644 --- a/Makefile +++ b/Makefile @@ -184,6 +184,23 @@ test-timers: test-timers-clean: $(MAKE) --directory=tools clean +guidedoc_sources = $(wildcard doc/guides/*.md) +guidedocs = $(addprefix out/,$(guidedoc_sources:.md=.html)) + +guidedoc_dirs = out/doc out/doc/guides/ out/doc/guides/assets + +# TODO(qard): Lifted api assets for now, may want to separate those. +guideassets = $(subst api_assets,guides/assets,$(addprefix out/,$(wildcard doc/api_assets/*))) + +$(guidedoc_dirs): + mkdir -p $@ + +out/doc/guides/assets/%: doc/guides_assets/% out/doc/guides/assets/ + cp $< $@ + +out/doc/guides/%.html: doc/guides/%.md $(NODE_EXE) + $(NODE) tools/doc/generate.js --format=html-guides --template=doc/guide-template.html $< > $@ + apidoc_sources = $(wildcard doc/api/*.markdown) apidocs = $(addprefix out/,$(apidoc_sources:.markdown=.html)) \ $(addprefix out/,$(apidoc_sources:.markdown=.json)) @@ -192,7 +209,9 @@ apidoc_dirs = out/doc out/doc/api/ out/doc/api/assets apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*))) -doc: $(apidoc_dirs) $(apiassets) $(apidocs) tools/doc/ $(NODE_EXE) +guidedocs: $(guidedoc_dirs) $(guideassets) $(guidedocs) tools/doc/ $(NODE_EXE) + +doc: $(apidoc_dirs) $(apiassets) $(apidocs) $(guidedoc_dirs) $(guideassets) $(guidedocs) tools/doc/ $(NODE_EXE) $(apidoc_dirs): mkdir -p $@ diff --git a/doc/guides/test.md b/doc/guides/test.md new file mode 100644 index 00000000000000..48228c598964bc --- /dev/null +++ b/doc/guides/test.md @@ -0,0 +1 @@ +# Hello, world diff --git a/tools/doc/generate.js b/tools/doc/generate.js index 7e47f4b0c2abb5..931845e367bc04 100644 --- a/tools/doc/generate.js +++ b/tools/doc/generate.js @@ -54,6 +54,14 @@ function next(er, input) { }); break; + // TODO: Merge guide and api html generators + case 'html-guides': + require('./guides.js')(input, inputFile, template, function(er, html) { + if (er) throw er; + console.log(html); + }); + break; + default: throw new Error('Invalid format: ' + format); } diff --git a/tools/doc/guides.js b/tools/doc/guides.js new file mode 100644 index 00000000000000..8f5b533b187981 --- /dev/null +++ b/tools/doc/guides.js @@ -0,0 +1,10 @@ +var fs = require('fs'); +var remark = require('remark'); +var path = require('path'); +var preprocess = require('./preprocess.js'); + +module.exports = toHTML; + +function toHTML(input, filename, template, cb) { + // TODO: Do stuff... +} From 23436718d9e0856f4d64d7834dde8def9a322458 Mon Sep 17 00:00:00 2001 From: Stephen Belanger Date: Mon, 25 Jan 2016 13:54:20 -0800 Subject: [PATCH 2/2] doc: can now generate guides html files --- Makefile | 2 +- doc/guides/test.md | 2 ++ tools/doc/guides.js | 46 ++++++++++++++++++++++++++++++++++++++---- tools/doc/package.json | 8 +++++++- 4 files changed, 52 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 4aa256bde8a8f7..89f679b9ca39ab 100644 --- a/Makefile +++ b/Makefile @@ -195,7 +195,7 @@ guideassets = $(subst api_assets,guides/assets,$(addprefix out/,$(wildcard doc/a $(guidedoc_dirs): mkdir -p $@ -out/doc/guides/assets/%: doc/guides_assets/% out/doc/guides/assets/ +out/doc/guides/assets/%: doc/api_assets/% out/doc/guides/assets/ cp $< $@ out/doc/guides/%.html: doc/guides/%.md $(NODE_EXE) diff --git a/doc/guides/test.md b/doc/guides/test.md index 48228c598964bc..67ce15643d0345 100644 --- a/doc/guides/test.md +++ b/doc/guides/test.md @@ -1 +1,3 @@ +# Table of Contents + # Hello, world diff --git a/tools/doc/guides.js b/tools/doc/guides.js index 8f5b533b187981..6f83e8fa5d7905 100644 --- a/tools/doc/guides.js +++ b/tools/doc/guides.js @@ -1,10 +1,48 @@ var fs = require('fs'); -var remark = require('remark'); var path = require('path'); -var preprocess = require('./preprocess.js'); + +var VFile = require('vfile'); +var remark = require('remark'); +var remarkHtml = require('remark-html'); +var slug = require('remark-slug'); +var toc = require('remark-toc'); +// TODO(qard): includes get hijacked by preprocess in generate script +// var include = require('remark-include'); module.exports = toHTML; -function toHTML(input, filename, template, cb) { - // TODO: Do stuff... +function makeVFile (input, filepath) { + var dir = path.dirname(filepath); + var ext = path.extname(filepath); + var name = path.basename(filepath, ext).slice(1); + return new VFile({ + directory: dir, + filename: name, + extension: ext, + contents: input + }); +} + +function render (template, content, cb) { + fs.readFile(template, function (err, res) { + if (err) return cb(err); + var body = res.toString(); + body = body.replace(/__CONTENT__/g, content); + cb(null, body); + }); +} + +function toHTML(input, filepath, template, cb) { + var processor = remark(); + processor.use(toc); + processor.use(slug); + processor.use(remarkHtml); + // TODO(qard): includes get hijacked by preprocess in generate script + // processor.use(include, { + // cwd: 'doc/guides' + // }); + + var file = makeVFile(input, filepath); + var content = processor.process(file); + render(template, content, cb); } diff --git a/tools/doc/package.json b/tools/doc/package.json index d87c9345b33f2e..33a84fbb52d576 100644 --- a/tools/doc/package.json +++ b/tools/doc/package.json @@ -7,7 +7,13 @@ "node": ">=0.6.10" }, "dependencies": { - "marked": "~0.1.9" + "marked": "~0.1.9", + "remark": "^3.2.2", + "remark-html": "^2.0.2", + "remark-include": "^1.0.1", + "remark-slug": "^4.0.0", + "remark-toc": "^2.0.1", + "vfile": "^1.3.1" }, "devDependencies": {}, "optionalDependencies": {},