builddocs - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

bin/builddocs.js

@@ -5,5 +5,27 @@ var fs = require("fs")
 
-var config = JSON.parse(fs.readFileSync(".builddocs", "utf8"))
-if (!config.name) config.name = JSON.parse(fs.readFileSync("package.json", "utf8")).name
+var name, main, templates, allowUnresolved = true, files = []
 
-console.log(build(config))
+function help(status) {
+  console.log("Usage: builddocs --name <name> --main <main> [--templates <templatedir>]\n         [--disallow-unresolved] [--help] <sourcefiles>")
+  process.exit(status)
+}
+
+for (var i = 2; i < process.argv.length; i++) {
+  var arg = process.argv[i]
+  if (arg == "--name") name = process.argv[++i]
+  else if (arg == "--main") main = process.argv[++i]
+  else if (arg == "--templates") templates = process.argv[++i]
+  else if (arg == "--disallow-unresolved") allowUnresolved = false
+  else if (arg.charAt(0) != "-") files.push(arg)
+  else help(arg == "--help" ? 0 : 1)
+}
+
+if (!main || !name || !files.length) help(1)
+
+console.log(build({
+  name: name,
+  main: main,
+  files: files.join(" "),
+  templates: templates,
+  allowUnresolvedTypes: allowUnresolved
+}))

package.json

 {
   "name": "builddocs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Build documentation files from getdocs-commented source code",
@@ -5,0 +5,0 @@ "main": "src/builddocs.js",

README.md

@@ -20,7 +20,7 @@ # builddocs
 
- * **`order`**`: string` When given, this should be a space-separated
-   string of file names, which determines the order in which the given
-   files are read. You don't have to provide the full paths, only the
-   filename part (for example `foo` for `/a/b/foojs`). Any files not
-   mentioned here are left at the end of the set of files.
+ * **`main`**`: string` The path to the main template, which should be
+   a Markdown file with `@itemName` placeholders where the generated
+   docs for the documented items in the source should be inserted.
+   builddocs will complain when the set of item placeholders does not
+   match the set of documented items.
 
@@ -27,0 +27,0 @@ * **`anchorPrefix`**`: ?string` Can be used to override the prefix

src/builddocs.js

@@ -13,18 +13,31 @@ var fs = require("fs")
 
-  var cx = new Context(config, data)
-  return cx.mold.defs.module()
+  var placed = Object.create(null)
+  var doc = markdown.render(fs.readFileSync(config.main, "utf8").replace(/(^|\n)@(\w+)(?=$|\n)/g, function(_, before, name, after) {
+    if (placed[name]) throw new Error("Item " + name + " is included in doc template twice")
+    if (!data.items[name]) throw new Error("Unknown item " + name + " included in doc template")
+    placed[name] = true
+    return before + before + '<div data-item="' + name + '"></div>\n'
+  }))
+  for (var name in data.items) if (!placed[name])
+    throw new Error("Item " + name + " is missing from the doc template")
+
+  var mold = loadTemplates(config, data)
+
+  return doc.replace(/<div data-item="([^"]+)"><\/div>/g, function(_, name) {
+    let item = data.items[name]
+    return mold.defs.item({item: item, name: name})
+  })
 }
 
-function Context(config, data) {
-  this.config = config
-  this.prefix = config.anchorPrefix == null ? config.name + "." : config.anchorPrefix
-  this.data = data
-  this.mold = this.loadTemplates()
+function prefix(config) {
+  var prefix = config.anchorPrefix
+  if (prefix == null) prefix = config.name + "."
+  return prefix
 }
 
-Context.prototype.loadTemplates = function() {
-  var mold = new Mold(this.moldEnv()), conf = this.config
+function loadTemplates(config, data) {
+  var mold = new Mold(moldEnv(config, data))
   mold.defs.markdown = function(text) {
     if (!text) return ""
-    return markdown.render(conf.markdownFilter ? conf.markdownFilter(text) : text)
+    return markdown.render(config.markdownFilter ? config.markdownFilter(text) : text)
   }
@@ -43,3 +56,3 @@ mold.defs.markdownFile = function(name) {
 
-  if (conf.templates) templateDir(conf.templates)
+  if (config.templates) templateDir(config.templates)
   templateDir(__dirname + "/../templates")
@@ -50,6 +63,6 @@
 
-function maybeLinkType(self, name) {
-  if (name in self.data.all) return "#" + self.prefix + name
+function maybeLinkType(config, data, name) {
+  if (name in data.all) return "#" + prefix(config) + name
   if (name.charAt(0) == '"') return false
-  var imports = self.config.imports, qualified = self.config.qualifiedImports
+  var imports = config.imports, qualified = config.qualifiedImports
   if (imports) for (var i = 0; i < imports.length; i++) {
@@ -60,6 +73,6 @@ var set = imports[i]
   }
-  if (qualified) for (var prefix in qualified) if (name.indexOf(prefix + ".") == 0) {
-    var inner = name.slice(prefix.length + 1)
-    if (Object.prototype.hasOwnProperty.call(qualified[prefix], inner))
-      return qualified[prefix][inner]
+  if (qualified) for (var pref in qualified) if (name.indexOf(pref + ".") == 0) {
+    var inner = name.slice(pref.length + 1)
+    if (Object.prototype.hasOwnProperty.call(qualified[pref], inner))
+      return qualified[pref][inner]
   }
@@ -69,28 +82,16 @@ if (builtins.hasOwnProperty(name)) return builtins[name]
 
-Context.prototype.moldEnv = function() {
-  var contentPos = 0
-
-  var self = this, env = {
-    moduleName: this.config.name,
-    prefix: this.prefix,
-    moduleText: this.data.extraText,
-    items: this.data.items,
-    pieces: this.data.pieces,
+function moldEnv(config, data) {
+  var env = {
+    prefix: prefix(config),
     linkType: function(type) {
-      var link = maybeLinkType(self, type.type)
-      if (!link && link !== false && !self.config.allowUnresolvedTypes)
+      var link = maybeLinkType(config, data, type.type)
+      if (!link && link !== false && !config.allowUnresolvedTypes)
         throw new Error("Unknown type '" + type.type + "' at " + type.loc.file + ":" + type.loc.line)
       return link
     },
-    anchor: function(item) {
-      return self.prefix + item.id
-    },
-    itemName: function(item) {
-      return /[^\.^]+$/.exec(item.id)[0]
-    },
     hasDescription: function(type) {
       if (type.description) return true
-      if (type.properties) for (let prop in type.properties)
+      if (type.properties) for (var prop in type.properties)
         if (env.hasDescription(type.properties[prop])) return true
-      if (type.params) for (let i = 0; i < type.params.length; i++)
+      if (type.params) for (var i = 0; i < type.params.length; i++)
         if (env.hasDescription(type.params[i])) return true
@@ -101,8 +102,4 @@ if (type.returns && type.returns.description) return true
   }
-  if (this.config.env) for (var prop in this.config.env) env[prop] = this.config.env[prop]
+  if (config.env) for (var prop in config.env) env[prop] = config.env[prop]
   return env
 }
-
-function notEmpty(obj) {
-  for (var _ in obj) return obj
-}

src/read.js

@@ -6,39 +6,14 @@ var fs = require("fs")
 exports.read = function(config) {
-  var items = Object.create(null), content = [], last
-  var files = filesFor(config)
+  var items = Object.create(null)
+  var files = config.files.split(" ").reduce(function(set, pat) {
+    return set.concat(glob.sync(pat))
+  }, [])
   files.forEach(function(filename) {
     last = null
     var file = fs.readFileSync(filename, "utf8")
-    getdocs.gather(file, {
-      filename: filename,
-      items: items,
-      onComment: function(block, text, _start, _end, startPos) {
-        var m
-        if (last && !block && startPos.line == last.loc.line + 1)
-          last.text += "\n" + text
-        else if (m = /^\s*!!(?:$|\s)/.exec(text))
-          content.push(last = {loc: {line: startPos.line, file: filename}, text: text.slice(m[0].length)})
-      }
-    })
+    getdocs.gather(file, {filename: filename, items: items})
   })
 
-  function isBefore(element, item) {
-    var fDiff = files.indexOf(element.loc.file) - files.indexOf(item.loc.file)
-    if (fDiff < 0) return true
-    return fDiff == 0 && element.loc.line < item.loc.line
-  }
-
-  let pieces = [], i = 0
-  for (let name in items) {
-    let item = items[name]
-    while (i < content.length && isBefore(content[i], item))
-      pieces.push({content: getdocs.stripComment(content[i++].text)})
-    pieces.push(item)
-  }
-  while (i < content.length)
-    pieces.push({content: getdocs.stripComment(content[i++].text)})
-
   return {
     items: items,
-    pieces: pieces,
     all: gatherAll({properties: items}, Object.create(null))
@@ -48,17 +23,2 @@ }
 
-function filesFor(config) {
-  var files = config.files.split(" ").reduce(function(set, pat) {
-    return set.concat(glob.sync(pat))
-  }, [])
-  if (!config.order) return files
-
-  var ordered = config.order.split(" ").map(function(pat) {
-    var re = new RegExp("\\/" + pat + "\\.\\w+$")
-    for (var i = 0; i < files.length; i++)
-      if (files[i].match(re)) return files.splice(i, 1)[0]
-    throw new Error("Order pattern " + pat + " does not match a file")
-  })
-  return ordered.concat(files)
-}
-
 function gatherAll(obj, target) {
@@ -65,0 +25,0 @@ if (obj.id) target[obj.id] = obj

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Worsened metrics

Total package byte prevSize

25572

decreased by-2.41%

Lines of code

282

decreased by-6.62%

No dependency changes