Medable · davideaquaro · Feb 13, 2023 · Jan 5, 2023 · Jan 10, 2023 · Feb 6, 2023
diff --git a/packages/mdctl-cli/tasks/docs.js b/packages/mdctl-cli/tasks/docs.js
@@ -1,43 +1,31 @@
 /* eslint-disable class-methods-use-this */
 
-const MdctlDocs = require('@medable/mdctl-docs'),
+const { generate } = require('@medable/mdctl-docs'),
       Task = require('../lib/task')
 
 class Docs extends Task {
 
   constructor() {
 
-    const options = {
-      debug: {
-        default: false,
-        type: 'boolean'
-      },
-      destination: {
-        default: '',
-        type: 'string'
-      },
-      module: {
-        default: '',
-        type: 'string'
-      },
+    const optionSpec = {
       source: {
-        default: '',
+        default: '.',
         type: 'string'
       },
-      verbose: {
-        default: false,
-        type: 'boolean'
+      destination: {
+        default: 'docs',
+        type: 'string'
       }
     }
 
-    super(options)
-    this.optionKeys = Object.keys(options)
+    super(optionSpec)
+    this.optionKeys = Object.keys(optionSpec)
 
   }
 
   async run(cli) {
-    const params = await cli.getArguments(this.optionKeys)
-    return MdctlDocs.generateDocumentation(params)
+    const options = await cli.getArguments(this.optionKeys)
+    return generate(options)
   }
 
   // ----------------------------------------------------------------------------------------------
@@ -60,12 +48,9 @@ class Docs extends Task {
     Arguments:
 
       options
-
-        --debug - tool debugging output (WIP)
+
         --destination - output directory
-        --module - documentation module name
         --source - source directory
-        --verbose - detailed output (WIP)
 `
   }
 

diff --git a/packages/mdctl-docs/__tests__/util.js b/packages/mdctl-docs/__tests__/util.js
@@ -0,0 +1,77 @@
+const {
+  capitalize,
+  capitalizeFirstCharacter,
+  cammelToSentence,
+  clone,
+  isObject,
+  removeExtention,
+  stringify
+} = require('../lib/util')
+
+describe('capitalize', function() {
+
+  it('should capitalize', function() {
+    expect(capitalize('string')).toBe('STRING')
+  })
+
+})
+
+describe('capitalizeFirstCharacter', function() {
+
+  it('should capitalize first character', function() {
+    expect(capitalizeFirstCharacter('string')).toBe('String')
+  })
+
+})
+
+describe('cammelToSentence', function() {
+
+  it('should convert cammel case to sentense case', function() {
+    expect(cammelToSentence('cammelCaseString')).toBe('Cammel Case String')
+  })
+
+})
+
+describe('clone', function() {
+
+  it('should clone an object literal', function() {
+
+    const object = { a: 'a' }
+
+    expect(clone(object)).not.toBe(object)
+
+  })
+
+})
+
+describe('isObject', function() {
+
+  it('should return true for an object literal', function() {
+    expect(isObject({})).toBe(true)
+      })
+
+  it('should return false for a string', function() {
+    expect(isObject('string')).toBe(false)
+  })
+
+  it('should return false for a boolean', function() {
+    expect(isObject(true)).toBe(false)
+  })
+
+})
+
+describe('removeExtention', function() {
+
+  it('should remove extention from filename', function() {
+    expect(removeExtention('data.json')).toBe('data')
+  })
+
+})
+
+describe('stringify', function() {
+
+  it('should stringify an object literal', function() {
+    expect(stringify({ a: 'a' })).toBe('{\"a\":\"a\"}')
+  })
+
+})
diff --git a/packages/mdctl-docs/lib/documentors/env.js b/packages/mdctl-docs/lib/documentors/env.js
@@ -0,0 +1,152 @@
+const path = require('path'),
+      fs = require('fs'),
+      { spawn } = require('child_process'),
+      util = require('../util'),
+      { loadPartials } = require('../handlebars'),
+      TEMPLATES = loadPartials(),
+      notTopLevelResource = ['dependencies', 'object', 'objects']
+
+function writeJSDocs(source, destination){
+
+  console.log('Generating JSDocs')
+
+  return new Promise((resolve, rejec
6DB6
t) => {
+    const jsdoc = path.join(__dirname, '../../node_modules/.bin/jsdoc'),
+          scriptDirectory = path.join(source, 'env'),
+          outputDirectory = path.join(destination, 'jsdoc'),
+          params = [
+            scriptDirectory,
+            '--recurse',
+            '--destination', outputDirectory
+          ]
+
+    try {
+
+      console.log(`Writing: ${outputDirectory}`)
+
+      const encoding = 'utf8',
+            proc = spawn(jsdoc, params, { encoding })
+
+      proc.stdout.on('data', (data) => console.log(`jsdoc stdout: ${data.toString(encoding)}`))
+      proc.stderr.on('data', (data) => console.warn(`jsdoc stderr: ${data.toString(encoding)}`))
+      proc.on('close', () => resolve())
+
+    } catch (err) {
+      reject(err)
+    }
+  })
+
+}
+
+function writeDocs(manifest, home, destination){
+
+  console.log('Generating env documentation')
+
+  for(const [resourceName, resourceManifest] of Object.entries(manifest).filter(([resourceName]) => !notTopLevelResource.includes(resourceName))){
+    if(fs.existsSync(path.join(home, 'env', resourceName))){
+      writeResource(resourceName, resourceManifest, home, destination)
+    }
+  }
+
+  if(fs.existsSync(path.join(home, 'env/objects'))){
+    writeObjects(manifest.objects, home, destination)
+  }
+
+  writePackageSummary(manifest, destination)
+
+}
+
+function writeResource(resourceName, resourceManifest, home, destination){
+
+  const includeAll = resourceManifest.includes.length === 1 && resourceManifest.includes[0] === '*',
+        objects = includeAll
+          ? util.listFiles(path.join(home, 'env', resourceName))
+            .map(filePath => util.readJson(filePath))
+          : resourceManifest.includes
+            .map(name => util.readJson(path.join(home, 'env', resourceName, `${name}.json`))),
+        content = TEMPLATES.MD_OBJECTS({
+          name: resourceName,
+          objects
+        })
+
+  util.writeFile({
+    content,
+    name: `${resourceName}.md`,
+    path: '.'
+  }, destination)
+
+}
+
+function writeObjects(objectManifests, home, destination){
+
+  for(const { name } of objectManifests){
+
+    const object = util.readJson(path.join(home, 'env/objects', `${name}.json`)),
+          content = TEMPLATES.MD_OBJECT({ object })
+
+    util.writeFile({
+      content,
+      name: `${name}.md`,
+      path: 'objects'
+    }, destination)
+  }
+
+}
+
+function writePackageSummary(manifest, destination){
+
+  const links = Object.keys(manifest)
+          .filter(key => !notTopLevelResource.includes(key))
+          .map(key => ({
+            name: key,
+            uri: `./${key}.md`
+          })),
+        sections = [
+          manifest.objects && {
+            label: 'Objects',
+            links: Object.values(manifest.objects).map(({ name }) => ({
+              name,
+              uri: `./objects/${name}.md`
+            }))
+          },
+          {
+            label: 'Scripts',
+            links: [
+              {
+                name: 'JSDocs',
+                uri: './jsdoc/'
+              }
+            ]
+          }
+        ].filter(section => section),
+        content = TEMPLATES.GITBOOK_SUMMARY({
+          links,
+          sections,
+          label: 'Package Summary'
+        })
+
+  util.writeFile({
+    content,
+    name: 'SUMMARY.md',
+    path: '.'
+  }, destination)
+}
+
+async function generate(source, destination){
+
+  console.log('Beginning documentation generation')
+
+  const home = path.resolve(process.cwd(), source),
+        manifest = util.readJson(path.join(home, 'manifest.json'))
+
+  writeDocs(manifest, home, destination)
+
+  await writeJSDocs(source, destination)
+
+  console.log('Documentation generation complete')
+
+}
+
+module.exports = {
+  generate,
+}
diff --git a/packages/mdctl-docs/lib/modules/index.js → packages/mdctl-docs/lib/documentors/index.js b/packages/mdctl-docs/lib/modules/index.js → packages/mdctl-docs/lib/documentors/index.js