咖啡文档

CoffeeScript 的 API 文档生成器

CoffeeDoc 是一个用于CoffeeScript的简单 API 文档生成器。它读取 CoffeeScript 类和函数定义中的 Python 样式文档字符串，通过Markdown传递它们并输出结果，就像易于阅读的 HTML 一样。

感谢apgwoz，CoffeeDoc 还可以为 Github生成wiki 页面！

CoffeeDoc 还可以将您的文档作为 JSON 返回，因此您可以通过外部文档系统（例如Sphinx ）运行它。

CoffeeDoc 的灵感来自优秀的Docco，适用于需要更多结构化 API 文档的项目。

CoffeeDoc 使用的文档字符串约定受 Python 启发，如下所示：

###
# CoffeeDoc example documentation #
 
This is a module-level docstring, and will be displayed at the top of the module documentation.
Documentation generated by [CoffeeDoc](http://github.com/omarkhan/coffeedoc)
###
 
class MyClass extends Superclass
    ###
    This docstring documents MyClass. It can include *Markdown* syntax,
    which will be converted to html.
    ###
    constructor: (@args) ->
        ### Constructor documentation goes here. ###
 
    method: (args) ->
        ### This is a method of MyClass ###
 
myFunc = (arg1, arg2, args...) ->
    ###
    This function will be documented by CoffeeDoc
    ###
    doSomething()

可以在此处查看从上述脚本生成的文档
。一个更有趣的例子，这是对 .coffeedoc 运行的结果
src/coffeedoc.coffee。

安装

CoffeeDoc 需要Node.js、CoffeeScript、eco和optimist。使用 npm 和以下命令安装：

sudo npm install -g coffeedoc

-g 选项全局安装 CoffeeDoc，将 coffeedoc 可执行文件添加到您的 PATH。如果您更愿意在本地安装，请省略 -g 选项。

您还可以使用 cake 从源代码安装。从源目录运行：

sudo cake install

用法

CoffeeDoc 可以从命令行运行：

Usage: coffeedoc [options] [targets]

Options:
  --output, -o      Set output directory                                            [default: "docs"]
  --ignore, -i      Files or directories to ignore
  --stdout          Direct all output to stdout instead of files
  --hide-private    Do not document methods beginning with an underscore
  --parser          Parser to use. Built-in parsers: commonjs, requirejs            [default: "commonjs"]
  --renderer        Renderer to use. Built-in renderers: html, gfm, json            [default: "html"]
  --indexTemplate   Override the default index template for the selected renderer
  --moduleTemplate  Override the default module template for the selected renderer
  --help, -h        Show this help and exit

如果 [targets] 是一个目录，CoffeeDoc 将递归地记录.coffee
在该目录下找到的所有文件。

如果您希望记录多个模块，请确保使用单个命令生成所有文档——这确保它们都将出现在
index.html文件中。

关于 Markdown 标题的注意事项

Markdown 使用#字符作为标题，例如

# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
###### Header 6

由于#在 CoffeeScript 块注释中使用 3 个或更多字符的序列会结束注释块，CoffeeDoc 允许\#在文档字符串中使用转义序列。因此，不要### Header使用\#\#\# Header或
##\# Header。丑陋，但它的工作原理。

怎么运行的

CoffeeDoc 使用 CoffeeScript 解析器为给定的源文件生成解析树。然后从解析树中提取相关信息：类和函数名称、类成员函数、函数参数列表和文档字符串。

文档字符串被定义为类或函数定义之后的第一个 herecomment 块。请注意，常规单行注释将被忽略。

然后将生成的文档信息传递给生态模板以生成 html 输出。

去做

• 文档测试

备择方案

• Docco用于文学编程风格的文档。
• Codo用于比 python 更红宝石的东西。

执照

CoffeeDoc 是 © 2012 Omar Khan，在 MIT 许可下发布。使用它，分叉它。