-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(docs-gen): Typedoc generator (#769)
- Loading branch information
1 parent
115d89d
commit 15373eb
Showing
96 changed files
with
11,201 additions
and
970 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
dist |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
module.exports = { | ||
modulePaths: ['<rootDir>/dist'], | ||
transform: { | ||
'^.+\\.tsx?$': 'ts-jest', | ||
}, | ||
verbose: true, | ||
collectCoverage: true, | ||
coverageReporters: ['text-summary'], | ||
collectCoverageFrom: ['<rootDir>/dist/**/*js'], | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
} | ||
} |
Oops, something went wrong.