JSdoc theme
npm install customer-better-docs-cn基于better-docs开发，主要用于生成中文文档，以及解决某些库的引用问题
基于JSDoc3生成 javascript / typescript 项目的文档，并且提供了 @category, @component and @optional 插件.
sh
npm install --save-dev customer-better-docs-cn
`
主题使用
使用命令行
全局安装了 jsdoc 的情况:
`
jsdoc your-documented-file.js -t ./node_modules/customer-better-docs-cn
`
使用npm配置文件
在你工程的 package.json 文件中添加:
`
"script": {
"docs": "jsdoc -c jsdoc.json"
}
`
在你的 jsdoc.json 文件中, 设置模板:
`json
"opts": {
"template": "node_modules/customer-better-docs-cn"
}
`
TypeScript 支持
customer-better-docs-cn 提供的插件生成 TypeScript 项目的文档.
咋用
更新你的 jsdoc.json 文档如下
`
...
"tags": {
"allowUnknownTags": ["optional"] //or true
},
"plugins": [
"node_modules/customer-better-docs-cn/typescript"
],
"source": {
"includePattern": "\\.(jsx|js|ts|tsx)$",
},
...
`
现在你可以使用 jsdoc 命令编译 TypeScript 文件.
怎么工作的?（不翻译了，需要的自己翻译）
It performs 4 operations:
* First of all it transpiles all .ts and .tsx files to .js, so that all comments used by you are treated
as a regular JSDoc comments.
Furhtermore it:
* Converts all your commented type aliases to @typedef
* Converts all your commented interface definitions to @interface,
* Converts descriptions for your public, protected, static class members
so they can be printed by JSDoc automatically.
示例
`
/**
* ActionRequest
* @memberof Action
* @alias ActionRequest
*/
export type ActionRequest = {
/**
* parameters passed in an URL
*/
params: {
/**
* Id of current resource
*/
resourceId: string;
/**
* Id of current record
*/
recordId?: string;
/**
* Name of an action
*/
action: string;
[key: string]: any;
};
}
`
转换为:
`
/**
* ActionRequest'
* @memberof Action'
* @alias ActionRequest'
* @typedef {object} ActionRequest'
* @property {object} params parameters passed in an URL'
* @property {string} params.resourceId Id of current resource'
* @property {string} [params.recordId] Id of current record'
* @property {string} params.action Name of an action'
* @property {any} params.{...}'
*/
`
Also you can comment the interface in a similar fashion:
`
/**
* JSON representation of an {@link Action}
* @see Action
*/
export default interface ActionJSON {
/**
* Unique action name
*/
name: string;
/**
* Type of an action
*/
actionType: 'record' | 'resource' | Array<'record' | 'resource'>;
/**
* Action icon
*/
icon?: string;
/**
* Action label - visible on the frontend
*/
label: string;
/**
* Guarding message
*/
guard?: string;
/**
* If action should have a filter (for resource actions)
*/
showFilter: boolean;
/**
* Action component. When set to false action will be invoked immediately after clicking it,
* to put in another words: tere wont be an action view
*/
component?: string | false | null;
}
`
or describe your class properties like that:
`
/**
* Class name
*/
class ClassName {
/**
* Some private member which WONT be in jsdoc (because it is private)
*/
private name: string
/**
* Some protected member which will go to the docs
*/
protected somethingIsA: number
/**
* And static member which will goes to the docs.
*/
static someStaticMember: number
public notCommentedWontBeInJSDoc: string
constructor(color: string) {}
}
`
@category 插件
customer-better-docs-cn 允许自定义左侧菜单项.
怎么用
更新你的 jsdoc.json 文件中 plugins如下:
`
...
"tags": {
"allowUnknownTags": ["category"] //or true
},
"plugins": [
"node_modules/customer-better-docs-cn/category"
],
...
`
接着你就可以使用 @category 标签:
`
/**
* Class description
* @category Category
*/
class YourClass {
....
}
`
@component plugin [BETA]
customer-better-docs-cn also allows you to document your React and Vue components automatically. The only thing you have to do is to add a @component tag. It will take all props from your components and along with an @example tag - will generate a __live preview__.
Installation instructions
Similar as before to add a plugin - you have to update the plugins section in your jsdoc.json file:
`
...
"tags": {
"allowUnknownTags": ["component"] //or true
},
"plugins": [
"node_modules/customer-better-docs-cn/component"
],
...
`
Since __component__ plugin uses parcel as a bundler you have to install it globally. To do this run:
`
if you use npm
npm install -g parcel-bundler
or yarn
yarn global add parcel-bundler
`
Usage
To document components simply add @component in your JSDoc documentation:
`jsx
/**
* Some documented component
*
* @component
*/
const Documented = (props) => {
const { text } = props
return (
{text}
)
}
Documented.propTypes = {
/**
* Text is a text
*/
text: PropTypes.string.isRequired,
}
export default Documented
`
The plugin will take the information from your PropTypes and put them into an array.
For Vue it looks similar:
`vue
`
In this case, props will be taken from props property.
Preview
@component plugin also modifies the behaviour of @example tag in a way that it can generate an actual __component preview__. What you have to do is to add an @example tag and return component from it:
React example:
`jsx
/**
* Some documented component
*
* @component
* @example
* const text = 'some example text'
* return (
*
* )
*/
const Documented = (props) => {
///...
}
`
Vue example 1:
`vue
`
Vue example 2:
`vue
`
You can put as many @example tags as you like in one component and "caption" each of them like this:
`javascript
/**
* @component
* @example Example usage of method1.
* // your example here
*/
`
Mixing components in preview
Also you can use multiple components which are documented with @component tag together. So lets say you have 2 components and in the seccond component you want to use the first one as a wrapper like this:
`javascript
// component-1.js
/**
* Component 1
* @component
*
*/
const Component1 = (props) => {...}
// component-2.js
/**
* Component 2
* @component
* @example
* return (
*
*
*
*
* )
*/
const Component2 = (props) => {...}
`
Wrapper component [only React]
Most probably your components will have to be run within a particular context, like within redux store provider or with custom CSS libraries.
You can simulate this by passing a component.wrapper in your jsdoc.json:
_(To read more about passing options - scroll down to __Customization__ section)_
`json
// jsdoc.json
{
"opts": {...},
"templates": {
"better-docs": {
"name": "AdminBro Documentation",
"component": {
"wrapper": "./path/to/your/wrapper-component.js",
},
"...": "...",
}
}
}
`
Wrapper component can look like this:
`javascript
// wrapper-component.js
import React from 'react'
import { BrowserRouter } from 'react-router-dom'
import { createStore } from 'redux'
import { Provider } from 'react-redux'
const store = createStore(() => ({}), {})
const Component = (props) => {
return (
{props.children}
)
}
export default Component
`
Styling React examples
customer-better-docs-cn inserts all examples within an iframe. This results in the following styling options:
1. If you pass styles inline - they will work right away.
2. For css modules to work with parcel bundler - you have to install postcss-modules package:
`
yarn add postcss-modules
`
and create a .postcssrc file:
`json
// .postcssrc
{
"modules": true
}
`
3. For styled-components you have to use wrapper component which looks like this:
`jsx
import React from 'react'
import { StyleSheetManager } from 'styled-components'
const Component = (props) => {
const { frameContext } = props
return (
{props.children}
)
}
export default Component
`
Adding commands to bundle entry file
@component plugin creates an entry file: .entry.js in your _docs_ output folder. Sometimes you might want to add something to it. You can do this by passing: component.entry option, which is an array of strings.
So let's say you want to add babel-polyfill and 'bulma.css' framework to your bundle. You can do it like this:
`json
// jsdoc.json
{
"opts": {...},
"templates": {
"better-docs": {
"name": "AdminBro Documentation",
"component": {
"entry": [
"import 'babel-polyfill';",
"import 'bulma/css/bulma.css';"
]
},
"...": "...",
}
}
}
`
自定义
首先, 需要说明的是 customer-better-docs-cn 继承自 default 模板. 这也是默认模板的参数有用的原因.自定义 customer-better-docs-cn 通过 options 的 templates['better-docs']. 在你的 jsdoc配置文件.
下面是使用 default 和 better-docs 模板的配置示例:
`json
{
"tags": {
"allowUnknownTags": ["category"]
},
"source": {
"include": ["./src"],
"includePattern": ".js$",
"excludePattern": "(node_modules/|docs)"
},
"plugins": [
"plugins/markdown",
"jsdoc-mermaid",
"node_modules/customer-better-docs-cn/category"
],
"opts": {
"encoding": "utf8",
"destination": "docs/",
"readme": "readme.md",
"recurse": true,
"verbose": true,
"tutorials": "./docs-src/tutorials",
"template": "better-docs"
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false,
"default": {
"staticFiles": {
"include": [
"./docs-src/statics"
]
}
},
"better-docs": {
"name": "Documentation",
"logo": "images/logo.png",
"copyright": "https://github.com",
"dateFormat": "dddMMMYYYY",
"trackingCode": "tracking-code-which-will-go-to-the-HEAD",
"hideGenerator": false,//是否隐藏页脚
"navigation": [
{
"label": "Github",
"href": "https://github.com/SoftwareBrothers/admin-bro"
},
{
"label": "Example Application",
"href": "https://admin-bro-example-app.herokuapp.com/admin"
}
]
}
}
}
``