feat(docs-gen): Typedoc generator (#769)

docs-gen/.gitignore

@@ -0,0 +1 @@
+dist

docs-gen/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 Cube Dev, Inc.
+Copyright (c) 2016 Thomas Grey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs-gen/README.md

@@ -0,0 +1,50 @@
+# typedoc-plugin-markdown
+
+A plugin for [TypeDoc](https://github.com/TypeStrong/typedoc) that enables TypeScript API documentation to be generated in Markdown.
+
+[![npm](https://img.shields.io/npm/v/typedoc-plugin-markdown.svg)](https://www.npmjs.com/package/typedoc-plugin-markdown)
+[![Build Status](https://travis-ci.org/tgreyuk/typedoc-plugin-markdown.svg?branch=master)](https://travis-ci.org/tgreyuk/typedoc-plugin-markdown)
+
+## What it does?
+
+The plugin will replace the default HTML theme with a built-in Markdown theme, and expose some additional arguments.
+
+By default, the Markdown theme will attempt to render standard CommonMark, suitable for the majority of Markdown engines.
+It follows the same structure and file patterns as the default HTML theme.
+
+## Installation
+
+```bash
+npm install --save-dev typedoc typedoc-plugin-markdown
+```
+
+## Usage
+
+```bash
+$ npx typedoc --plugin typedoc-plugin-markdown [args]
+```
+
+### Note:
+
+- The `--plugin` arg is optional - if omitted all installed plugins will run.
+- If using with the default HTML theme or other themes, use `--plugin none` to switch the plugin off.
+- The plugin needs to be executed from the same location as `typedoc`. Either run as an npm script or make sure to run `npx typedoc`.
+
+## Arguments
+
+The following arguments can be used in addition to the default [TypeDoc arguments](https://github.com/TypeStrong/typedoc#arguments).
+
+- `--theme <markdown|docusaurus|docusaurus2|vuepress|bitbucket|path/to/theme>`<br>
+  Specify the theme that should be used. Defaults to `markdown`. Please read [Markdown Themes](https://github.com/tgreyuk/typedoc-plugin-markdown/blob/master/THEMES.md) for further details.
+- `--namedAnchors`<br>
+  Use HTML named anchors as fragment identifiers for engines that do not automatically assign header ids.
+- `--hideSources`<br>
+  Do not print source file link rendering.
+- `--hideBreadcrumbs`<br>
+  Do not print breadcrumbs.
+- `--skipSidebar`<br>
+  Do not update the `sidebar.json` file when used with `docusaurus` or `docusaurus2` theme.
+
+## License
+
+[MIT](https://github.com/tgreyuk/typedoc-plugin-markdown/blob/master/LICENSE)

docs-gen/THEMES.md

@@ -0,0 +1,151 @@
+# Markdown Themes
+
+By default, the Markdown theme will attempt to render standard CommonMark, suitable for the majority of Markdown engines.
+It follows the same structure and file patterns as the default HTML theme (see [typedoc-default-themes](https://github.com/TypeStrong/typedoc-default-themes)).
+
+The plugin also comes packaged with some additional built-in themes and can also be extended with a custom theme.
+
+- [Built-in themes](#built-in-themes)
+- [Writing a custom Markdown theme](#writing-a-custom-markdown-theme)
+
+## Writing a custom markdown theme
+
+The Markdown theme packaged with the plugin can also be extended with a custom Markdown theme using the standard TypeDoc theming pattern as per https://typedoc.org/guides/themes/.
+
+### Create a theme.js class
+
+As per the theme docs create a `theme.js` file which TypeDoc will then attempt to load from a given location.
+
+_mytheme/custom-theme.js_
+
+```js
+const MarkdownTheme = require('typedoc-plugin-markdown/dist/theme');
+
+class CustomMarkdownTheme extends MarkdownTheme.default {
+  constructor(renderer, basePath) {
+    super(renderer, basePath);
+  }
+}
+
+exports.default = CustomMarkdownTheme;
+```
+
+### Theme resources
+
+By default the theme will inherit the resources of the Markdown theme (https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/src/resources).
+
+These can be replaced and updated as required.
+
+### Building the theme
+
+#### CLI
+
+```
+npx typedoc ./src --plugin typedoc-plugin-markdown --theme ./mytheme/custom-theme --out docs
+```
+
+#### API
+
+```js
+const { Application } = require('typedoc');
+const path = require('path');
+
+const app = new Application();
+app.bootstrap({
+  module: 'CommonJS',
+  target: 'ES5',
+  readme: 'none',
+  theme: path.join(__dirname, 'mytheme', 'custom-theme'),
+  plugin: 'typedoc-plugin-markdown',
+});
+
+app.generateDocs(app.expandInputFiles(['./src']), 'docs');
+```
+
+See https://typedoc.org/guides/installation/#node-module
+
+## Built-in themes
+
+### `docusaurus` / `docusaurus2`
+
+The --out path is assumed be a Docusaurus docs directory.
+
+- Adds Front Matter to pages to support Docusaurus [Markdown Headers](https://docusaurus.io/docs/en/doc-markdown#markdown-headers).
+- Appends releavant JSON to website/sidebars.json|sidebars.js, to support [sidebar navigation](https://docusaurus.io/docs/en/navigation).
+
+#### Output
+
+```
+root-directory
+├── docs
+│   ├── myapi
+│   |   ├── classes
+│   │   ├── enums
+│   │   ├── interfaces
+│   │   ├── index.md
+│   │
+└── website
+    ├── sidebars.json
+
+```
+
+#### Adding links in siteconfig
+
+Manually add the index page to headerLinks in the [siteConfig.js](https://docusaurus.io/docs/en/site-config) to access the api from header.
+
+```js
+headerLinks: [
+  { doc: "myapi/index", label: "My API" },
+],
+```
+
+### `vuepress`
+
+- Adds Front Matter to pages.
+- The --out path is assumed be a Vuepress docs directory.
+- Will create:
+
+  - `.vuepress/api-sidebar.json` to be used with [sidebar](https://vuepress.vuejs.org/default-theme-config/#sidebar).
+  - `.vuepress/api-sidebar-relative.json` to be used with [multiple sidebars](https://vuepress.vuejs.org/default-theme-config/#multiple-sidebars).
+  - `.vuepress/config.json`
+
+#### Examples
+
+```js
+const apiSideBar = require('./api-sidebar.json');
+
+// Without groups
+module.exports = {
+  themeConfig: {
+    sidebar: ['some-content', ...apiSideBar],
+  },
+};
+
+// With groups
+module.exports = {
+  themeConfig: {
+    sidebar: ['some-content', { title: 'API', children: apiSideBar }],
+  },
+};
+```
+
+```js
+const apiSideBarRelative = require('./api-sidebar-relative.json');
+
+// Multiple sidebars
+module.exports = {
+  themeConfig: {
+    sidebar: {
+      '/guide/': ['some-content'],
+      '/api/': apiSideBarRelative,
+      '/': ['other'],
+    },
+  },
+};
+```
+
+### `bitbucket`
+
+_Note: this theme applicable to Bitbucket Cloud. If using Bitbucket Server please use the `--namedAnchors` argument to fix anchor links._
+
+- Parses internal anchor links to support Bitbucket's internal anchor linking.

docs-gen/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  modulePaths: ['<rootDir>/dist'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest',
+  },
+  verbose: true,
+  collectCoverage: true,
+  coverageReporters: ['text-summary'],
+  collectCoverageFrom: ['<rootDir>/dist/**/*js'],
+};

docs-gen/package.json

@@ -1,20 +1,50 @@
 {
-  "name": "docs-gen",
+  "name": "cubejs-typedoc-plugin",
   "version": "0.0.1",
-  "dependencies": {
-    "@babel/generator": "^7.4.0",
-    "@babel/parser": "^7.4.2",
-    "@babel/preset-env": "^7.3.4",
-    "@babel/preset-react": "^7.0.0",
-    "@babel/standalone": "^7.3.4",
-    "@babel/traverse": "^7.4.0",
-    "@babel/types": "^7.4.0",
-    "fs-extra": "^8.1.0",
-    "inflection": "^1.12.0",
-    "jsdoc": "^3.6.3"
-  },
+  "description": "A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.",
+  "main": "dist/index.js",
+  "files": [
+    "dist/"
+  ],
   "scripts": {
-    "generate": "jsdoc -t template ../packages/cubejs-client-core/src/*.js -d ../docs/Cube.js-Frontend/@cubejs-client-core.md"
+    "lint": "tslint --project ./tsconfig.json",
+    "generate": "yarn build && typedoc --excludeExternals --includeDeclarations --plugin ../docs-gen/dist/index.js --hideSources --hideIndexes --out ../docs/Cube.js-Frontend --name @cubejs-client-core ../packages/cubejs-client-core/index.d.ts",
+    "dev-generate": "copyfiles --up 1 ./src/**/*.hbs ./dist/ && yarn generate",
+    "build": "rm -rf dist && tsc --sourceMap false --declaration false && copyfiles --up 1 ./src/**/*.hbs ./dist/",
+    "watch": "tsc-watch",
+    "prepublishOnly": "yarn test",
+    "pretest": "yarn lint && yarn build",
+    "test": "jest",
+    "compile": "tsc src/index.ts",
+    "test:updateSnapshot": "jest --updateSnapshot",
+    "fixtures": "rm -rf ./test/fixtures && node ./tasks/fixtures.js",
+    "examples": "yarn build && rm -rf out && node ./tasks/link-plugin.js && yarn examples:html && yarn examples:md",
+    "examples:html": "typedoc --tsconfig ./test/stubs/tsconfig.json --options ./test/options.json --plugin none --out ./out/html",
+    "examples:md": "typedoc --tsconfig ./test/stubs/tsconfig.json --options ./test/options.json --out ./out/md"
+  },
+  "author": "Cube Dev, Inc.",
+  "license": "MIT",
+  "engines": {
+    "node": ">= 8.0.0"
   },
-  "license": "MIT"
+  "peerDependencies": {
+    "typedoc": ">=0.17.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^9.0.1",
+    "@types/jest": "^25.2.3",
+    "@types/node": "^14.0.9",
+    "copyfiles": "^2.3.0",
+    "jest": "^26.0.1",
+    "ts-jest": "^26.1.0",
+    "tsc-watch": "^4.2.9",
+    "tslint": "^6.1.2",
+    "typedoc": "0.17.7",
+    "typescript": "3.9.x"
+  },
+  "dependencies": {
+    "fs-extra": "^9.0.0",
+    "handlebars": "^4.7.6",
+    "inflection": "^1.12.0"
+  }
 }