jacksontian / doxmate

文档伴侣

Doxmate 不再为文档而发愁

来源

过去通常要自己维护API文档，这会是一件比较蛋疼的事情。所幸我们有dox，dox可以帮我们解析注解。但是dox不能帮我们任意生成文档。于是就有了doxmate，doxmate基于dox的注解对象，加入模板。在遵循Github和CommonJS的约定后，doxmate可以帮你的模块包快速生成文档。

Installation

安装doxmate为全局工具：

$ npm install doxmate -g

Usage

此处将以doxmate项目自身作为例子：

// 签出doxmate项目
$ git clone git://github.com/JacksonTian/doxmate.git ~/git/doxmate
// 去到项目目录
$ cd doxmate
$ doxmate build
// 在docs目录下将会得到文档
$ open ~/git/doxmate/doc/index.html
// 或者 -o folder，可以将文档生成到指定的目录下
$ doxmate build -o ~/output

选择模版

// 带上-s参数后，可以选择doxmate提供的几种模板
$ doxmate build -s wordpress

自定义模版

如果doxmate提供的几个模板不能满足你的需求

// 查看doxmate目前已有的模板
$ doxmate theme list
// 在当前项目目录导出主题模板
$ doxmate theme export
// 将会在当前目录下生成{doxmate-templates/主题名}的目录
// 带上-s参数后，可以选择doxmate提供的几种模板
$ doxmate theme export -s pomelo
// 通过doxmate build创建文档的时，优先读取该目录
// 导出主题模板后，自行修改，即可实现自定义模板的目的

查看文档效果

通过将生成的文档放到gh-pages分支中，可以通过链接http://jacksontian.github.com/doxmate直接查看效果。

目前提供三种模板

默认风格

wordpress风格

pomelo风格

Github与CommonJS规范

• 每个github项目下应该有一个README.md文件
• CommonJS规范建议文档存在在doc目录下
• CommonJS规范建议代码存在在lib目录下

Doxmate将会扫描项目下的README.md和doc目录下的md文件，通过markdown渲染，生成页面。扫描lib目录下的文件，通过dox解析内容，生成API文档页面。

贡献者

以下数据由git-summary于2012-10-27生成：

 project  : doxmate
 repo age : 11 months
 active   : 21 days
 commits  : 89
 files    : 94
 authors  : 
    71  Jackson Tian            79.8%
    10  youxiachai              11.2%
     5  Lei Zongmin             5.6%
     3  aleafs                  3.4%

License (MIT)

MIT许可，请自由享用。

Copyright (c) 2012 Jackson Tian
http://weibo.com/shyvo

The MIT License

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.

捐赠

如果您觉得本模块对您有帮助，欢迎请作者一杯咖啡

doxmate's Issues

不能识别 @api 注释

如以下注释信息不能正确生成：

/**
 * 合并对象
 *
 * @api private
 */

微信公众号接收消息会触发三次

微信公众号接收消息会触发三次

左边子导航功能失效

1.doxmate build （3种模版下）
2.左边子导航功能失效

内容 h1 h2 等标签 id 无法正确输出

如何写注释来说明一个Object对象应该包含的属性

注释文本：

/**
 * 创建日志记录器
 *
 * @param {String} name 日志记录器名称
 * @param {Object} options
 *   - {String} path 日志主目录，默认为./log
 *   - {Number} interval 保存周期，默认为2000ms
 *   - {String} level 等级，fatal > error > warn > info > debug，默认为debug
 *   - {Boolean} output 是否在控制台输出，默认为true
 * @api public
 */

输出的页面显示如下：

这样很明显是影响阅读的。建议对于未知的注释类型，可以把它隐藏起来（起码比显示undefined强），或者有神马好的注释写法来说明上面的options参数？

菜单标题太长，标题会调皮地跑出来

我也没想出太好的解决办法，但是方法名就这么长，又不能随便改……

Live Bug Demo: http://gridjs.org/docs/API.html

不支持PHP吗？

➜ * git:(master) ✗ cd Application
➜ Application git:(master) ✗ doxmate build
{ [Error: Command failed:
module.js:340
throw err;
^
Error: Cannot find module '/Applications/XAMPP/xamppfiles/htdocs/**/Application/package.json'
at Function.Module._resolveFilename (module.js:338:15)
at Function.Module._load (module.js:280:25)
at Module.require (module.js:364:17)
at require (module.js:380:17)
at Object.exports.process (/usr/local/lib/node_modules/doxmate/lib/doxmate.js:164:13)
at Object. (/usr/local/lib/node_modules/doxmate/bin/doxmate-build:36:9)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
] killed: false, code: 8, signal: null }

doxmate error

你好，我按照官方的操作测试了一下，为何显示错误？
系统为64位 win7

谢谢！

API Docs导航栏问题

如上图，左边导航栏A应该设置成浮动的，否则当拖动滚动条后，这个导航栏就看不见了，不便于阅读。

同时API索引B应该放到左边导航栏中

顶部导航栏的「API Docs」点击后背景不会发生变化

在「Changelog」界面是顶部导航栏相应的链接会有不一样的背景，但「API Docs」没有。

在Wordpress主题下。

左侧目录太长时，(MAC.Chrome下)滚动到底部，目录导航会闪动。

另，目前导航好像是抓取二级标题生成的，多级目录要怎么配置？

能生成PHP文档吗？

怎么生成PHP文档哪？

package.json文件中没有设置keywords时出错

出错信息如下：

undefined:24
  throw err;
        ^
ReferenceError: F:\github\doxmate\templates\index.html:6
    4|     <div class="span3 bs-docs-sidebar">
    5|       <% include sidebar %>
 >> 6|     </div>
    7|     <div class="span9">
    8|       <% for (var key in apis) {
    9|         var api = apis[key];

keywords is not defined
    at buf.push..
<div class="container content">
  <div class="row">
    <div class="span3 bs-docs-sidebar">
      .buf (eval at <anonymous> (F:\github\doxmate\node_modules\ejs\lib\ejs.js:234:12))
    at eval (eval at <anonymous> (F:\github\doxmate\node_modules\ejs\lib\ejs.js:234:12))
    at exports.compile (F:\github\doxmate\node_modules\ejs\lib\ejs.js:239:15)
    at Object.exports.render (F:\github\doxmate\node_modules\ejs\lib\ejs.js:277:13)
    at Object.exports.process (F:\github\doxmate\lib\doxmate.js:162:57)
    at Object.<anonymous> (F:\github\doxmate\bin\doxmate:47:9)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)

Arguments to path.resolve must be strings

frank$ doxmate -i ./doxmate/

path.js:313
throw new TypeError('Arguments to path.resolve must be strings');
^
TypeError: Arguments to path.resolve must be strings
at Object.exports.resolve (path.js:313:15)
at Object. (/usr/local/lib/node_modules/doxmate/bin/doxmate:38:25)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
at node.js:901:3

添加抽取TODO的功能

//TODO: Get the proper amount of characters, and cut by last

优先使用当前目录下的templates

如果当前目录下有templates目录，则优先使用当前templates里的模板

执行命令的时候直接报错了

PS E:\doxmate> doxmate build
{ Error: spawn D:\nodejs\node_modules\doxmate\bin\doxmate-build ENOENT
at Process.ChildProcess._handle.onexit (internal/child_process.js:201:19)
at onErrorNT (internal/child_process.js:379:16)
at process._tickCallback (internal/process/next_tick.js:114:19)
at Function.Module.runMain (module.js:692:11)
at startup (bootstrap_node.js:194:16)
at bootstrap_node.js:666:3
errno: 'ENOENT',
code: 'ENOENT',
syscall: 'spawn D:\nodejs\node_modules\doxmate\bin\doxmate-build',
path: 'D:\nodejs\node_modules\doxmate\bin\doxmate-build',
spawnargs: [],
cmd: 'D:\nodejs\node_modules\doxmate\bin\doxmate-build' }
现在解决了, 提了pull

Markdown编译问题

issue #2中提到的Markdown页面问题，虽然现在能生成页面，但是有些格式貌似不支持：

比如这个文件：https://github.com/leizongmin/tinyliquid/blob/master/doc/filters.md

被编译成下面这样：

Reference Error

模板js代码高亮还有如何配置关闭代码输出

js 代码高亮应该是模板的问题..不知道有没有默认加上的需要?

还有就是配置代码是否输出到文档,代码没必要在doc 文档上面显示吧....

1

1

生成文档的界面问题

1.首页在Chrome下显示位置有重叠：

2.没有指定页面编码，浏览器默认为GBK时显示乱码：

3.顶栏后面那两个链接是原来的doc目录里有的Markdown文件，但是没有正确转为HTML：