build: update api generator

Author: mrholek

build/docgen.config.js

@@ -1,17 +1,26 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
 'use strict'
 
 const path = require('path')
-const templates = require('./docgen.templates')
+const pkg = require('./../package.json')
+// const templates = require('./docgen.templates')
 
 module.exports = {
   componentsRoot: 'src/components', // the folder where CLI will start searching for components.
   components: '**/[A-Z]*.ts', // the glob to define what files should be documented as components (relative to componentRoot)
-  outDir: 'docs/api', // folder to save components docs in (relative to the current working directry)
+  outDir: `docs/${pkg.config.version_short}/api`, // folder to save components docs in (relative to the current working directry)
   getDocFileName: (componentPath) =>
     componentPath.replace(/\.ts$/, '.md'), // specify the name of the input md file
   getDestFile: (file, config) =>
     path.join(config.outDir, file).replace(/\.ts$/, '.api.md'), // specify the name of the output md file
-  templates,
+  // templates,
+  templates: {
+    // global component template wrapping all others see #templates
+    component: require('./templates/component'),
+    events: require('./templates/events'),
+    props: require('./templates/props'),
+    slots: require('./templates/slots'),
+  },
   docsRepo: 'profile/repo',
   docsBranch: 'master',
   docsFolder: '',

build/docgen.templates.js

@@ -0,0 +1,45 @@
+'use strict'
+
+module.exports = (renderedUsage, doc, config, fileName, requiresMd, { isSubComponent, hasSubComponents }) => {
+  const { displayName, description, docsBlocks, tags, functional } = doc;
+  const { deprecated, author, since, version, see, link } = tags || {};
+  const frontMatter = [];
+  if (!config.outFile && deprecated) {
+      // to avoid having the squiggles in the left menu for deprecated items
+      // use the frontmatter feature of vuepress
+      frontMatter.push(`title: ${displayName}`);
+  }
+  if (hasSubComponents) {
+      // show more than one level on subcomponents
+      frontMatter.push('sidebarDepth: 2');
+  }
+  return `${frontMatter.length && !isSubComponent
+      ? `
+---
+${frontMatter.join('\n')}
+---
+`
+      : ''}
+${isSubComponent || hasSubComponents ? '#' : ''}### ${deprecated ? `~~${displayName}~~` : displayName}
+
+${deprecated ? `> **Deprecated** ${deprecated[0].description}\n` : ''}
+${description ? '> ' + description : ''}
+
+${functional ? renderedUsage.functionalTag : ''}
+${author ? author.map(a => `Author: ${a.description}\n`) : ''}
+${since ? `Since: ${since[0].description}\n` : ''}
+${version ? `Version: ${version[0].description}\n` : ''}
+${see ? see.map(s => `[See](${s.description})\n`) : ''}
+${link ? link.map(l => `[See](${l.description})\n`) : ''}
+
+${renderedUsage.props}
+${renderedUsage.methods}
+${renderedUsage.events}
+${renderedUsage.slots}
+${docsBlocks ? '---\n' + docsBlocks.join('\n---\n') : ''}
+
+${requiresMd.length
+      ? '---\n' + requiresMd.map(component => component.content).join('\n---\n')
+      : ''}
+`;
+};

build/templates/component.js

@@ -0,0 +1,40 @@
+'use strict'
+
+function mdclean(input) {
+	return input.replace(/\r?\n/g, '<br>').replace(/\|/g, '\\|')
+}
+
+function formatProperties(properties) {
+	if (!properties) {
+		return ''
+	}
+	return properties
+		.map(property => {
+			const { name, description, type } = property
+			if (!type) {
+				return ''
+			}
+			return `**${name}** \`${type.names.length ? type.names.join(', ') : ''}\` - ${description}`
+		})
+		.join('\n')
+}
+
+const tmpl = (events) => {
+	let ret = ''
+	events.forEach(evt => {
+		const { description = '', ...e } = evt
+		const readableProperties = e.properties ? `${formatProperties(e.properties)}` : ''
+		ret += `| <code>${mdclean(e.name)}</code> | ${mdclean(readableProperties)} | ${mdclean(description)}\n`
+	})
+	return ret
+}
+
+module.exports = (events, opt = {}) => {
+	return `
+${opt.isSubComponent || opt.hasSubComponents ? '#' : ''}#### Events
+
+  | Event name     | Properties     | Description  |
+  | -------------- |--------------- | -------------|
+  ${tmpl(events)}
+  `
+}

build/templates/events.js

@@ -0,0 +1,38 @@
+'use strict'
+function mdclean(input) {
+	return input.replace(/\r?\n/g, '<br>').replace(/\|/g, '\\|')
+}
+function isTag(v) {
+  return !!v.content;
+}
+const renderTags = (tags) => {
+  if (!tags) {
+    return '';
+  }
+  return Object.entries(tags)
+    .map(([tag, values]) => {
+    return values.map(v => `<br/>\`@${tag}\` ${isTag(v) ? v.content : v.description}`).join('');
+  })
+  .join('');
+};
+const tmpl = (props) => {
+  let ret = '';
+  props.forEach(pr => {
+    const p = pr.name
+    let t = pr.description ?? ''
+    t += renderTags(pr.tags)
+    const n = pr.type?.name ?? ''
+    const v = pr.values?.map(pv => `\`${pv}\``).join(', ') ?? '-'
+    const d = pr.defaultValue?.value ?? ''
+    ret += `| <code>${mdclean(p)}</code> | ${mdclean(t)} | ${mdclean(n)} | ${mdclean(v)} | ${mdclean(d)} |\n`;
+  });
+  return ret;
+};
+module.exports = (props, opt = {}) => {
+    return `
+${opt.isSubComponent || opt.hasSubComponents ? '#' : ''}#### Props
+  | Prop name     | Description | Type      | Values      | Default     |
+  | ------------- | ----------- | --------- | ----------- | ----------- |
+  ${tmpl(props)}
+  `;
+};

build/templates/props.js

@@ -0,0 +1,38 @@
+'use strict'
+
+function mdclean(input) {
+	return input.replace(/\r?\n/g, '<br>').replace(/\|/g, '\\|')
+}
+
+const formatBindings = bindings => {
+    if (!bindings) {
+        return '';
+    }
+    return bindings
+        .map(binding => {
+        const { name, description, type } = binding;
+        if (!type) {
+            return '';
+        }
+        return `**${name}** \`${type.name === 'union' && type.elements
+            ? type.elements.map(({ name: insideName }) => insideName).join(', ')
+            : type.name}\` - ${description}`;
+    })
+        .join('\n');
+};
+
+module.exports = (slots, opt = {}) => {
+    return `
+${opt.isSubComponent || opt.hasSubComponents ? '#' : ''}#### Slots
+
+  | Name          | Description  | Bindings |
+  | ------------- | ------------ | -------- |
+  ${slots
+        .map(slot => {
+        const { description, bindings, name } = slot;
+        const readableBindings = bindings ? `${formatBindings(bindings)}` : '';
+        return `| ${mdclean(name)} | ${mdclean(description || '')} | ${mdclean(readableBindings)} |`; // replace returns by <br> to allow them in a table cell
+    })
+        .join('\n')}
+`;
+};