customer-better-docs-cn v1.0.22

基于better-docs开发，主要用于生成中文文档，以及解决某些库的引用问题

基于JSDoc3生成 javascript / typescript 项目的文档，并且提供了 @category, @component and @optional 插件.

例子

英文版的例子: https://softwarebrothers.github.io/example-design-system/index.html

安装

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 文件中, 设置模板:

"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:

/**
 * Some documented component
 * 
 * @component
 */
const Documented = (props) => {
  const { text } = props
  return (
    <div>{text}</div>
  )
}

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:

<script>
/**
 * @component
 */
export default {
  name: 'ExampleComponent',
  props: {
    spent: {
      type: Number,
      default: 30,
    },
    remaining: {
      type: Number,
      default: 40,
    }
  },
}
</script>

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:

/**
 * Some documented component
 * 
 * @component
 * @example
 * const text = 'some example text'
 * return (
 *   <Documented text={text} />
 * )
 */
const Documented = (props) => {
  ///...
}

Vue example 1:

<script>
/**
 * @component
 * @example
 * <ExampleComponent :spent="100" :remaining="50"></ExampleComponent>
 */
export default {
  name: 'ExampleComponent',
  //...
}
</script>

Vue example 2:

<script>
/**
 * @component
 * @example
 * {
 *   template: `<Box>
 *     <ProgressBar :spent="spent" :remaining="50"></ProgressBar>
 *     <ProgressBar :spent="50" :remaining="50" style="margin-top: 20px"></ProgressBar>
 *   </Box>`,
 *   data: function() {
 *     return {spent: 223};
 *   }
 * }
 */
export default {
  name: 'ExampleComponent',
  //...
}
</script>

You can put as many @example tags as you like in one component and "caption" each of them like this:

/**
 * @component
 * @example <caption>Example usage of method1.</caption>
 * // 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:

// component-1.js
/**
 * Component 1
 * @component
 * 
 */
const Component1 = (props) => {...}

// component-2.js
/**
 * Component 2
 * @component
 * @example
 * return (
 *   <Component1>
 *     <Component2 prop1={'some value'}/>
 *     <Component2 prop1={'some other value'}/>
 *   </Component1>
 * )
 */
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)

// jsdoc.json
{
    "opts": {...},
    "templates": {
        "better-docs": {
            "name": "AdminBro Documentation",
            "component": {
              "wrapper": "./path/to/your/wrapper-component.js",
            },
            "...": "...",
        }
    }
}

Wrapper component can look like this:

// 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 (
    <React.Fragment>
      <head>
        <link type="text/css" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bulma/0.7.5/css/bulma.css" />
      </head>
      <Provider store={store}>
        <BrowserRouter>
          {props.children}
        </BrowserRouter>
      </Provider>
    </React.Fragment>
  )
}

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:

// .postcssrc
{
	"modules": true
}

3. For styled-components you have to use wrapper component which looks like this:

import React from 'react'
import { StyleSheetManager } from 'styled-components'

const Component = (props) => {
  const { frameContext } = props
  return (
    <StyleSheetManager target={frameContext.document.head}>
      {props.children}
    </StyleSheetManager>
  )
}

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:

// 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 模板的配置示例:

{
    "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"
                }
            ]
        }
    }
}