first stab at a docs generator

Author: heapwolf

README.md

@@ -46,12 +46,10 @@ Each param is associaated with the last function or method.
 Each comment is associated with the last keyword.
 
 # CLI
-Hyper-docs cli will output an AST. It will also accept an AST as input
-and compile to either html (`--html`) or markdown (`--md`) pending on the
-specified flag.
+Hyper-docs cli will output an AST. No args produces an HTML document.
 
 ```bash
-hyper-docs /path/to/projects | ./bin/docs --html
+hyper-docs /path/to/projects | ./bin/docs > path/to/api.html
 ```
 
 # PARSER

compile.js

@@ -1,71 +1,212 @@
+//
+// Produces a single page (searchable) document with a TOC.
+//
+// Yeah, its a lot of messy string templating. If you have
+// a better idea, feel free to make a pull request :)
+//
+const fs = require('fs')
 const marked = require('marked')
-const hl = require('highlight.js')
 
+marked.setOptions({
+  renderer: new marked.Renderer()
+})
+
+const escapeString = s => {
+  s = s.replace('&', '&')
+    .replace('>', '>')
+    .replace('<', '&lt;')
+    .replace('\'', '&#x27;')
+    .replace('"', '&quot;')
+    .replace('`', '&#x60;')
+  return s
+}
+
+//
+// Return Types
+//
+const templateReturnType = type => `
+  |Return Type|Description|
+  |:---|:---|
+  |${type.return.TYPE}|${type.return.comment}|
+`
+
+//
+// Properties
+//
+const templateProperties = members => {
+  const props = members.filter(m => m.type === 'property')
+
+  if (!props.length) {
+    return '' // there are no operators
+  }
+
+  let header = [
+    `### PROPERTIES\n`,
+    `|Type|Name|Description|`,
+    `|:---|:---|:----------|`
+  ]
+
+  const rows = props.map(prop =>
+    `|${prop.TYPE}|${prop.name}|${prop.comment || ''}|`
+  )
+
+  return [...header, ...rows].join('\n')
+}
+
+//
+// Operators
+//
 const templateOperators = members => {
   const operators = members.filter(m => m.type === 'operator')
 
-  let table =  `|Operator|Description|\n`
-      table += `|:-------|:----------|\n`
+  if (!operators.length) {
+    return '' // there are no operators
+  }
 
-  table += operators.map(operator => {
-    return `|${operator.name}|${operator.comment}|`
-  }).join('\n')
+  let header = [
+    `### OPERATORS\n`,
+    `|Operator|Description|`,
+    `|:-------|:----------|`
+  ]
+
+  const rows = operators.map(operator =>
+    `|${operator.name}|${operator.comment || ''}|`
+  )
+
+  return [...header, ...rows].join('\n')
+}
+
+//
+// Params
+//
+const templateParams = type => {
+  if (!type.params || !Object.keys(type.params).length) {
+    return ''
+  }
+
+  return [
+    ``,
+    `|Parameter|Description|`,
+    `|:---|:---|`,
+    ...Object.keys(type.params).map(key => {
+      const param = type.params[key]
+      return `|${key}|${param.comment}|`
+    })
+  ].join('\n')
+}
+
+//
+// Methods
+//
+const templateMethods = members => {
+  const methods = members.filter(m => m.type === 'method')
+
+  if (!methods.length) {
+    return '' // there are no operators
+  }
+
+  const header = [`### METHODS\n`]
+
+  const rows = methods.map(method => {
+    return [
+      `#### ${method.name}`,
+      `${method.comment}`,
+      `\`\`\``,
+      method.raw,
+      `\`\`\``,
+      templateReturnType(method),
+      templateParams(method),
+      ``
+    ].join('\n')
+  })
 
-  return table
+  return [...header, ...rows].join('\n')
 }
 
-const templateClass = (key, type) => `
-### \`${key}\`
+const templateClassOrStruct = (key, type) => `
+## ${escapeString(key)}
 ${type.comment}
 
 ${templateOperators(type.members)}
+
+${templateMethods(type.members)}
+
+${templateProperties(type.members)}
 `
 
 const templateFunction = (key, type) => `
-### \`${key}\`
+## ${escapeString(key)}
 ${type.comment}
+
+\`\`\`
+${type.raw}
+\`\`\`
+
+${templateReturnType(type)}
+
+${templateParams(type)}
 `
 
-const template = ast => `
-# [${ast.namespace}](${ast.repo})
+const createMD = ast => {
+  if (!ast.namespace) return ''
+
+  return `
+# ${ast.namespace.join('::')}
 
-## TYPES
 ${
   Object.keys(ast.types).map(key => {
     const type = ast.types[key]
 
     return type.members
-      ? templateClass(key, type)
+      ? templateClassOrStruct(key, type)
       : templateFunction(key, type)
   }).join('\n')
 }
 `
+}
 
-const createHTML = s => {
-  marked.setOptions({
-    renderer: new marked.Renderer(),
-    highlight: code => hl.highlightAuto(code).value
-  })
+module.exports = buffers => {
+  const toc = {}
+  const groups = {}
 
-  return marked(s)
-}
+  buffers.forEach(ast => {
+    if (!ast.namespace) return
 
-const createMD = ast => {
-  if (!ast.namespace) {
-    return ''
-  } else {
-    ast.namespace = ast.namespace.join('::')
-  }
+    const ns = ast.namespace.join('::')
 
-  return template(ast)
-}
+    const output = marked(createMD(ast))
 
-module.exports = (buffers, type) => {
-  buffers.forEach(ast => {
-    const output = type === 'html'
-      ? createHTML(createMD(ast))
-      : createMD(ast)
+    if (ast.types) {
+      toc[ns] = toc[ns] || []
+      toc[ns].push(...Object.keys(ast.types))
+    }
+
+    groups[ns] = groups[ns] || []
+    groups[ns].push(output)
+  })
 
-    process.stdout.write(output)
+  const flattened = []
+
+  Object.keys(toc).forEach(key => {
+    const k = escapeString(key)
+    flattened.push(`<a href="${k}">${k}</a><ul>`)
+
+    flattened.push(...toc[key].map(type =>
+      `<li>${escapeString(type)}</li>`))
+
+    flattened.push(`</ul>`)
   })
+
+  const output = `
+    <div class="toc">
+      ${flattened.join('\n')}
+    </div>
+
+    <div class="docs">
+      ${Object.values(groups).map(buf => buf.join('')).join('\n')}
+    </div>
+  `
+
+  const template = fs.readFileSync(`${__dirname}/template.txt`, 'utf8')
+  process.stdout.write(template.replace('DOCS', output))
 }

index.js

@@ -65,7 +65,7 @@ const parseUrl = s => {
 // Read all files from a path and parse their headers for docs
 //
 function main (argv) {
-  if (argv[0] === '--md' || argv[0] === '--html') {
+  if (!argv.length) {
     let buffers = fs
       .readFileSync(0, 'utf8')
       .split(os.EOL)
@@ -78,8 +78,7 @@ function main (argv) {
       process.exit(1)
     }
 
-    const type = argv[0].slice(2)
-    compile(buffers, type)
+    compile(buffers)
     return
   }
 

package-lock.json

@@ -18,7 +18,6 @@
   },
   "homepage": "https://github.com/datcxx/hyper-docs#readme",
   "dependencies": {
-    "highlight.js": "^9.15.6",
     "marked": "^0.6.2"
   }
 }