tidy-jsdoc-o2

tidy-jsdoc

A minimalist and clean jsdoc template.

Features

• Custom styles via CSS variables
• Code syntax highlighting via Prism.js

Preview

Note Latest Version 1.0 is considered a breaking change because the design changes significantly.

Examples

• Newton Graph Library
• Using tidy-jsdoc? Open an issue to add your documentation here.

Based on the default jsdoc template and inspired in design by vue.js documentation and docsify.

Looking for the old design?

If you want keep the old design, version your package.json appropriately. Preview old designs in the images folder.

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/ 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.

{
    "opts": {    //命令行参数，在配置文件中配置了就不要敲命令了
        "encoding": "utf8",               //文件编码utf8
        "destination": "./o2web/api/",          //输出目标文件夹
        "recurse": true,                 //是否递归抽取sorce/include配置的文件夹
        "template" : "./node_modules/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:

{
  "metadata": "...",
  "styles": {
    "text-color": "#111",		
    "primary-color": "blue",
    "heading-color": "var(--primary-color)"
  }	
}

This would output in your document <head>:

<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.

Development

For more information about creating jsdoc templates, see the jsdoc GitHub repository.

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.