Fixes #12: Add ability to output markdown

README.md

@@ -1,39 +1,40 @@
-# aml2html
-[![Build Status](https://travis-ci.org/aml-org/aml2html.svg?branch=master)](https://travis-ci.org/aml-org/aml2html)
+# aml2doc
+[![Build Status](https://travis-ci.org/aml-org/aml2doc.svg?branch=master)](https://travis-ci.org/aml-org/aml2doc)
 
-Convert AML Vocabularies & Dialects to HTML.
+Convert AML Vocabularies & Dialects to documentation.
 
 ## Installation
 ```sh
-$ git clone git@github.com:aml-org/aml2html.git
-$ cd aml2html
+$ git clone git@github.com:aml-org/aml2doc.git
+$ cd aml2doc
 $ npm install
 ```
 
 ## Usage
 CLI command notation (*note the required `--` before arguments*):
 ```
-Usage: npm run aml2html -- [options] <outputDir>
+Usage: npm run aml2doc -- [options] <outputDir>
 
-Convert AML Vocabularies & Dialects to HTML
+Convert AML Vocabularies & Dialects to documentation.
 
 Options:
   -d, --indir <path>     Path to input directory to convert. Takes precedence over --infile.
   -f, --infile <path>    Path to input file to convert (default: [])
+  -s, --syntax <name>    Output syntax (html or md) (default: "html")
   -c, --css <path>       Custom css file path (default: [])
   -g, --cfg <path>       Configuration file path
-  -h, --help             output usage information
+  -h, --help             Output usage information
   -t, --templates <path> Path to optional custom templates for the documentation
 ```
 
 E.g.:
 ```sh
-$ npm run aml2html -- ./outdir --infile=test_data/amf/dialects/canonical_webapi.yaml --infile=test_data/amf/dialects/oas20.yaml --infile=test_data/amf/dialects/validation.yaml --infile=test_data/music/dialect/playlist.yaml
+$ npm run aml2doc -- ./outdir --infile=test_data/amf/dialects/canonical_webapi.yaml --infile=test_data/amf/dialects/oas20.yaml --infile=test_data/amf/dialects/validation.yaml --infile=test_data/music/dialect/playlist.yaml
 ```
 
 Or using `--indir` option:
 ```sh
-$ npm run aml2html -- ./outdir --indir=./test_data
+$ npm run aml2doc -- ./outdir --indir=./test_data
 ```
 
 
@@ -78,7 +79,7 @@ This file can be used when invoking the HTML generator in the following way:
 
 E.g.
 ```sh
-$ npm run aml2html -- ./outdir --indir=./test_data --cfg=/path/to/cfg.js
+$ npm run aml2doc -- ./outdir --indir=./test_data --cfg=/path/to/cfg.js
 ```
 
 Configuration files will be searched relative to the working directory of the node interpreter.

bin/aml2html.js → bin/aml2doc.js

@@ -2,18 +2,19 @@
 
 const program = require('commander')
 
-const aml2html = require('../src/index')
+const aml2doc = require('../src/index')
 const utils = require('../src/utils')
 
 program
   .arguments('<outputDir>')
   .action(outputDir => {
     program.outputDir = outputDir
   })
-  .name('aml2html')
-  .description('Convert AML Vocabularies & Dialects to HTML')
+  .name('aml2doc')
+  .description('Convert AML Vocabularies & Dialects to documentation.')
   .option('-d, --indir <path>', 'Path to input directory to convert. Takes precedence over --infile.')
   .option('-f, --infile <path>', 'Path to input file to convert', utils.collectOpt, [])
+  .option('-s, --syntax <name>', 'Output syntax (html or md)', 'html')
   .option('-c, --css <path>', 'Custom css file path', utils.collectOpt, [])
   .option('-g, --cfg <path>', 'Configuration file path')
   .option('-t, --templates <path>', 'Optional path to custom templates for the documentation')
@@ -28,4 +29,4 @@ if (!(program.infile.length > 0 || program.indir)) {
   program.help()
 }
 
-aml2html(program)
+aml2doc(program)

package.json

@@ -1,9 +1,10 @@
 {
-  "name": "@aml-org/aml2html",
-  "version": "0.1.3",
+  "name": "@aml-org/aml2doc",
+  "version": "0.1.4",
+  "description": "Convert AML Vocabularies & Dialects to documentation",
   "main": "src/index.js",
   "license": "MIT",
-  "repository": "git://github.com/aml-org/aml2html",
+  "repository": "git://github.com/aml-org/aml2doc",
   "dependencies": {
     "amf-client-js": "^4.0.4",
     "commander": "^3.0.2",
@@ -16,11 +17,11 @@
     "registry": "https://npm.pkg.github.com/"
   },
   "bin": {
-    "aml2html": "bin/aml2html.js"
+    "aml2doc": "bin/aml2doc.js"
   },
   "scripts": {
     "lint": "standard",
-    "aml2html": "node bin/aml2html.js",
+    "aml2doc": "node bin/aml2doc.js",
     "test": "npm run lint && nyc mocha -R spec --bail test/*.test.js"
   },
   "devDependencies": {

src/data_collectors.js

@@ -18,7 +18,7 @@ function collectVocabularyData (doc, ctx, acc) {
       vocabularyData.usage = usage[0]['@value']
     }
     vocabularyData.slug = utils.slugify(vocabularyData.name + '_vocab')
-    vocabularyData.htmlName = `${vocabularyData.slug}.html`
+    vocabularyData.pageName = vocabularyData.slug
     console.log(`Collecting nodes info for vocabulary ${id}`)
     vocabularyData.nodeMappings = collectVocabularyNodesData(
       doc, vocabularyData, ctx).sort(utils.nameSorter)
@@ -46,7 +46,7 @@ function collectDialectData (doc, ctx, acc, ontologyTerms) {
       dialectData.usage = usage[0]['@value']
     }
     dialectData.slug = utils.slugify(dialectData.name)
-    dialectData.htmlName = `${dialectData.slug}.html`
+    dialectData.pageName = dialectData.slug
     console.log(`Collecting nodes info for dialect ${id}`)
     dialectData.nodeMappings = collectNodesData(
       doc, dialectData, ctx, ontologyTerms)
@@ -91,9 +91,9 @@ function collectVocabularyNodesData (doc, dialectData, ctx) {
           dialectName: dialectData.name,
           dialectLabel: ctx.config.labelMapping(dialectData.name)
         }
-        // htmlName
+        // pageName
         nodeData.slug = utils.slugify(`${nodeData.name}_${cred.type}`)
-        nodeData.htmlName = utils.makeSchemaHtmlName(
+        nodeData.pageName = utils.makeSchemaPageName(
           dialectData.slug, nodeData.slug)
         // save
         acc[nodeId] = nodeData
@@ -120,9 +120,9 @@ function collectNodesData (doc, dialectData, ctx, ontologyTerms) {
           dialectName: dialectData.name,
           dialectLabel: ctx.config.labelMapping(dialectData.name)
         }
-        // htmlName
+        // pageName
         nodeData.slug = utils.slugify(nodeData.name)
-        nodeData.htmlName = utils.makeSchemaHtmlName(
+        nodeData.pageName = utils.makeSchemaPageName(
           dialectData.slug, nodeData.slug)
 
         const isUnion = node.query('@type')
@@ -198,7 +198,7 @@ function collectLinkPropsData (doc, node, dialectSlug, ontologyTerms, ctx) {
         }
         const decl = doc.query(`amldoc:declares[@id=${rangeId}]`)
         if (decl) {
-          data.rangeHtmlName = utils.makeSchemaHtmlName(
+          data.rangePageName = utils.makeSchemaPageName(
             utils.slugify(decl.parent().query('> core:name @value')),
             utils.slugify(data.rangeName))
         }
@@ -270,7 +270,7 @@ function collectCommonNavData (dialectsData, ctx) {
       return {
         name: name,
         label: ctx.config.labelMapping(name),
-        htmlName: data.htmlName,
+        pageName: data.pageName,
         active: false
       }
     }),
@@ -288,7 +288,7 @@ function collectNavData (dialectData, commonNavData, ctx) {
       return {
         name: name,
         label: ctx.config.labelMapping(name),
-        htmlName: data.htmlName,
+        pageName: data.pageName,
         active: false
       }
     })

src/index.js

@@ -9,7 +9,7 @@ const collect = require('./data_collectors')
 let TMPL_DIR = path.join(utils.TMPL_DIR)
 
 /** Runs all the logic. */
-async function aml2html (program) {
+async function aml2doc (program) {
   let ctx = utils.getDefaultContext()
   await amf.AMF.init()
 
@@ -85,8 +85,8 @@ async function aml2html (program) {
     // Render dialect overview template
     utils.renderTemplate(
       { ...dialectData, ...ctx.config, ...links },
-      path.join(TMPL_DIR, 'dialect.mustache'),
-      path.join(outDir, dialectData.htmlName))
+      path.join(TMPL_DIR, program.syntax, 'dialect.mustache'),
+      path.join(outDir, `${dialectData.pageName}.${program.syntax}`))
 
     // Render nodeMappings item data
     dialectData.nodeMappings.forEach(nodeData => {
@@ -97,8 +97,8 @@ async function aml2html (program) {
       nodeData.css = program.css
       utils.renderTemplate(
         { ...nodeData, ...ctx.config },
-        path.join(TMPL_DIR, 'node.mustache'),
-        path.join(outDir, nodeData.htmlName))
+        path.join(TMPL_DIR, program.syntax, 'node.mustache'),
+        path.join(outDir, `${nodeData.pageName}.${program.syntax}`))
     })
   })
 
@@ -113,10 +113,10 @@ async function aml2html (program) {
       ...ctx.config,
       ...indexLinks
     },
-    path.join(TMPL_DIR, 'index.mustache'),
-    path.join(outDir, 'index.html'))
+    path.join(TMPL_DIR, program.syntax, 'index.mustache'),
+    path.join(outDir, `index.${program.syntax}`))
 
   utils.copyStaticFiles(outDir)
 }
 
-module.exports = aml2html
+module.exports = aml2doc

src/utils.js

@@ -58,21 +58,19 @@ function parseHashValue (id) {
   return afterHash
 }
 
-/** Renders Mustache template with data and writes it to an HTML file.
+/** Renders Mustache template with data and writes it to a file.
  *
  * @param data Data to be renreder in a template.
- * @param tmplType Template type. Must match type-specific template
-                   folders names.
  * @param tmplPath Mustache template path.
- * @param htmlPath Output HTML path.
+ * @param outPath Output file path.
  */
-function renderTemplate (data, tmplPath, htmlPath) {
+function renderTemplate (data, tmplPath, outPath) {
   console.log(
     `Rendering "${tmplPath}" template`,
     data.id ? `for ${data.id}` : '')
   const tmplStr = fs.readFileSync(tmplPath, 'utf-8')
-  const htmlStr = Mustache.render(tmplStr, data)
-  fs.writeFileSync(htmlPath, htmlStr)
+  const renderedStr = Mustache.render(tmplStr, addTmplUtils(data))
+  fs.writeFileSync(outPath, renderedStr)
 }
 
 /* Sorts objects by property. To be used in Array.sort() */
@@ -88,14 +86,14 @@ function sorterBy (p) {
   }
 }
 
-/* Makes a slug used in html names creation. */
+/* Makes a slug used in page urls creation. */
 function slugify (val) {
   return val.split(' ').join('').toLowerCase()
 }
 
-/* Creates an html page name for nodeMappings item. */
-function makeSchemaHtmlName (dialectSlug, schemaName) {
-  return `schema_${dialectSlug}_${schemaName}.html`
+/* Creates a schema page name for nodeMappings item. */
+function makeSchemaPageName (dialectSlug, schemaName) {
+  return `schema_${dialectSlug}_${schemaName}`
 }
 
 /* Marks item with matching name as active/selected. */
@@ -238,6 +236,22 @@ function getOntologyTerms (ontologyObj) {
   return ontologyTerms
 }
 
+/* Adds template utility functions */
+function addTmplUtils (data) {
+  return {
+    ...data,
+    stripn: stripn
+  }
+}
+
+/* Strips newlines */
+function stripn () {
+  return (text, render) => {
+    const rendered = render(text)
+    return rendered ? rendered.split('\n').join(' ') : rendered
+  }
+}
+
 module.exports = {
   walkSync: walkSync,
   getJsonLdGraph: getJsonLdGraph,
@@ -249,11 +263,12 @@ module.exports = {
   nameSorter: sorterBy('name'),
   sorterBy: sorterBy,
   slugify: slugify,
-  makeSchemaHtmlName: makeSchemaHtmlName,
+  makeSchemaPageName: makeSchemaPageName,
   markActive: markActive,
   getDefaultContext: getDefaultContext,
   loadConfig: loadConfig,
   collectOpt: collectOpt,
+  addTmplUtils: addTmplUtils,
   processLinks: processLinks,
   collectJsonGraphs: collectJsonGraphs,
   getOntologyTerms: getOntologyTerms

templates/dialect.mustache → templates/html/dialect.mustache

@@ -27,7 +27,7 @@
           <hr>
           {{#navData.dialects}}
             <p class="dialects-nav-item {{^active}}in{{/active}}active-nav-item">
-              <a href="{{{htmlName}}}" title="{{name}}">{{name}}</a>
+              <a href="{{{pageName}}}.html" title="{{name}}">{{name}}</a>
             </p>
           {{/navData.dialects}}
         </div>
@@ -36,7 +36,7 @@
           <hr>
           {{#navData.nodeMappings}}
             <p class="schemas-nav-item {{^active}}in{{/active}}active-nav-item">
-              <a href="{{{htmlName}}}" title="{{name}}">{{name}}</a>
+              <a href="{{{pageName}}}.html" title="{{name}}">{{name}}</a>
             </p>
           {{/navData.nodeMappings}}
         </div>
@@ -76,7 +76,7 @@
         <ul class="dialect-schemas-list">
           {{#nodeMappings}}
             <li class="dialect-schemas-list-item">
-              <a href="{{{htmlName}}}" title="{{label}}">{{label}}</a>
+              <a href="{{{pageName}}}.html" title="{{label}}">{{label}}</a>
             </li>
           {{/nodeMappings}}
         </ul>

templates/index.mustache → templates/html/index.mustache

@@ -26,7 +26,7 @@
           <hr>
           {{#navData.dialects}}
             <p class="dialects-nav-item {{^active}}in{{/active}}active-nav-item">
-              <a href="{{{htmlName}}}" title="{{name}}">{{name}}</a>
+              <a href="{{{pageName}}}.html" title="{{name}}">{{name}}</a>
             </p>
           {{/navData.dialects}}
         </div>