npm package: @o2oa/tidy-jsdoc-o2
Description: A clean JSDoc3 template
Author: o2group
Latest version: 0.0.26
Deprecated: false

# tidy-jsdoc

[![Build Status](https://travis-ci.org/julie-ng/tidy-jsdoc.svg?branch=master)](https://travis-ci.org/julie-ng/tidy-jsdoc)
[![Known Vulnerabilities](https://snyk.io//test/github/julie-ng/tidy-jsdoc/badge.svg?targetFile=package.json)](https://snyk.io//test/github/julie-ng/tidy-jsdoc?targetFile=package.json)

A minimalist and clean [jsdoc](https://jsdoc.app/index.html) template. 

 ### Features

 - Custom styles via [CSS variables](#adjusting-theme-with-css-variables)
 - Code syntax highlighting via [Prism.js](https://prismjs.com/)

## Preview

Note Latest Version 1.0 is considered a _breaking change_ because the design changes significantly. 

#### Examples

- [Newton Graph Library](https://julie-ng.github.io/newtonjs-graph/)
- Using tidy-jsdoc? Open an issue to add your documentation here.

<img src="./images/v1-preview-newtonjs.png" alt="Version 1.0 - Preview" style="max-width:100%;">

Based on the [default jsdoc template](https://github.com/jsdoc/jsdoc/tree/master/templates) and inspired in design by [vue.js documentation](https://vuejs.org/v2/api/) and [docsify](https://docsify.js.org).

#### Looking for the old design?

If you want keep the old design, version your `package.json` appropriately. Preview old designs in the [images folder](./images/).

Note: the old designs ^0.3.0 will not be updated or maintained.

## Usage

### Add Dependency

To use this jsdoc template in a project, first install the packages:

```
npm install --save-dev jsdoc tidy-jsdoc-o2
```

### Generate Docs

Once you've configured jsdoc and added syntax to your JavaScript files, you can generate the HTML files like so, optionally including a readme file:

```
jsdoc --readme README.md -c jsdoc.json
```

### Configure JSDoc

Then configure jsdoc to use the tidy template. Below is an example `jsdoc.json` configuration file. Be sure to adjust

- **template**  
	Points to `./node_modules/tidy-jsdoc-o2`

- **prism-theme**  
	Optionally pick a prismjs theme for styling your code. Defaults to "prism-tomorrow-night". Choose from templates available in [`./static/styles/vendor/`](./static/styles/vendor/) folder

- **destination**  
	Output is `./docs/`, allowing for easy GitHub Pages publishing.

- **metadata**  
	Customize title, logo, etc.

- **styles**  
	Let's your customize colors, etc. See details below.

```javascript
{
    "opts": {    //命令行参数，在配置文件中配置了就不要敲命令了
        "encoding": "utf8",               //文件编码utf8
        "destination": "./o2web/api/",          //输出目标文件夹
        "recurse": true,                 //是否递归抽取sorce/include配置的文件夹
        "template" : "./node_modules/o2oa/tidy-jsdoc-o2", //模板路径
        "prism-theme": "prism-custom", //模板中的代码块样式主题
        "readme" : "./o2web/jsdoc_static/home/README.md" //首页
        //"tutorials": "./o2web/tutorials" //如果有教程，对应教程目录
    },

    "tags": {
        "allowUnknownTags": true, //允许jsdoc中未命名的标签
        "dictionaries": [   //标签库
            "jsdoc",
            "closure"
        ]
    },
    "source": {
        "include": [ //需要抽取文档的源文件夹，顺序和搜索结果的顺序有关
            "./o2web/source/o2_core/o2/xScript",
            "./o2web/source/x_desktop/js/o2m.api.js",
            "./o2web/source/x_component_process_Xform",
            "./o2web/source/x_component_cms_Xform"
        ],
        "includePattern": ".+\\.js(doc|x)?$", //抽取的源文件名称正则表达式
        "excludePattern": "(^|\\/|\\\\)_" //排除的源文件正则表达式
    },
    "plugins": [ //启用插件
        "plugins/markdown", //把markdown转成html
        "plugins/summarize" //为每个doclet生成摘要
    ],
    "templates": {  //模板参数
        "cleverLinks": false, //@link标签是否呈现为纯文本
        "monospaceLinks": false,
        "default": {
            "staticFiles": { //静态文件目录
                "include": [
                    "./o2web/jsdoc_static"
                ]
            }
        }
    },
    "metadata": {
        "title": "O2OA前台API", //最终生成的文档中标题
        "title_prefix" : "O2OA WebAPI", //html title标题前缀
        "title_suffix" : " | O2OA开发平台" //标题后缀
    },
    "o2" : {
        "actionOutPath" : "./o2server/{actionRoot}/src/main/webapp/describe/jsdoc/{actionName}.json",
        //"actionOutPath" : "./o2web/jsdoc/{actionRoot}/{actionName}.json",
        "actionOutExamplePath" : "./o2web/jsdoc_static/actionOut_examples/{actionRoot}.json"
    },
    "search" : {
        "enable" : true,
        "results_title" : "<span class='search-results-count'></span> results matching <span class='search-query'></span>",
        "no_results_title" : "No results matching '<span class='search-query'></span>'",
        "placeholder" : "输入关键字搜索"
    }
}
//执行命令: jsdoc -c ./o2web/jsdoc.conf.json -q version=v5.3.5
```

## Customize the Template

### Adjusting Theme with CSS variables

As of version 1.0, this template is styled via css variabbles, so you can adjust it to your brand. Inside your `jsdoc.json` configuration file, add an addional `styles` property, for example:

```javascript
{
  "metadata": "...",
  "styles": {
    "text-color": "#111",		
    "primary-color": "blue",
    "heading-color": "var(--primary-color)"
  }	
}
```

This would output in your document `<head>`:

```html
<style>
  :root {
    --text-color: #111;
    --primary-color: blue;
    --heading-color: var(--primary-color);
  }
<style>
```
The keys and values are arbitrary, but the CSS should be valid. For a full list of the available variables, see [_vars.scss](./static/styles/_vars.scss).


## Development

For more information about creating jsdoc templates, see the [jsdoc GitHub repository](https://github.com/jsdoc/jsdoc/tree/master/templates).

When editing SCSS, build the CSS automatically like so:

```
npm run sass:watch
```

Note: you'll have to commit **both** the scss and css files.