Biscotto

Build Status

Biscotto is a tool for generating CoffeeScript documentation. The underlying architecture was based on codo; however, this project uses a variant of the excellent TomDoc notation, instead of the more verbose JSDoc. It also has many more niceties.

Features

  • Detects classes, methods, constants, mixins & concerns.
  • Generates a nice site to browse your code documentation in various ways.
  • Intermediate JSON output to transform into any output
  • Can generate a metadata blob for more advanced usage (see below for more information)

Installing

npm install biscotto

Comment parsing with TomDoc

API documentation is written in the TomDoc notation. Originally conceived for Ruby, TomDoc lends itself pretty nicely to CoffeeScript.

There are some slight changes in the parse rules to match CoffeeScript. Briefly, here's a list of how you should format your documentation.

Visibility

Every class and method should start with one of three phrases: Public:, Internal:, and Private:. During the documentation generation process, you can flag whether or not to include Internal and Private members via the options passed in. If you don't have one of these status indicators, Biscotto will assume the global visibility (more on this below).

# Public: This is a test class with `inline.dot`. Beware.
class TestClassDocumentation

Method arguments

Each method argument must start with the argument name, followed by a dash (-), and the description of the argument:

argument - Some words about the arg!

Hash options are placed on a newline and begin with a colon:

options - These are the options:
          :key1 - Blah blah.
          :key2 - Blah
# Public: Does some stuff.
#
# something - Blah blah blah. Fah fah fah? Foo foo foo!
# something2 - Bar bar bar. Cha cha cha!!
# opts - The options
#        :speed - The {String} speed
#        :repeat -  How many {Number} times to repeat
#        :tasks - The {Tasks} tasks to do
bound: (something, something2, opts) =>

Examples

The examples section must start with the word "Examples" on a line by itself. The next line should be blank. Every line thereafter should be indented by two spaces from the initial comment marker:

# A method to run.
#
# Examples
#
#  biscotto = require 'biscotto'
#  file = (filename, content) ->
#    console.log "New file %s with content %s", filename, content
#  done = (err) ->
#    if err
#      console.log "Cannot generate documentation:", err
#    else
#      console.log "Documentation generated"
#  biscotto.run file, done
run: ->

Return types

When returning from a method, your line must start with the word Returns. You can list more than one Returns per method by separating each type on a different line.

# Private: Do it!
#
# Returns {Boolean} when it works.
returnSingleType: ->

# Internal: Does some thing.
#
# Returns an object with the keys:
#   :duration - A {Number} of milliseconds.
returnAHash: =>

Deviation from TomDoc

GitHub Flavored Markdown

Biscotto documentation is processed with GitHub Flavored Markdown.

Automatic link references

Biscotto comments are parsed for references to other classes, methods, and mixins, and are automatically linked together.

There are several different link types supported:

  • Normal URL links: {http://coffeescript.org/} or [Try CoffeeScript](http://coffeescript.org/)
  • Link to a class or a mixin: {Animal::Lion} or [The mighty lion]{Animal::Lion}
  • Direct link to an instance method: {Animal.Lion::walk} or [The lion walks]{Animal.Lion::walk}
  • Direct link to a class method: {Animal.Lion.constructor} or [A new king was born]{Animal.Lion.constructor}

If you are referring to a method within the same class, you can omit the class name: {::walk} or {.constructor}.

As an added bonus, wrapping default JavaScript types--like {String}, {Number}, {Boolean} etc.--have links automatically generated to MDN.

Here's an example of using links:

# This links out to the `long` method of the same class.
#
# See {::internalLinkLong} for more info.
#
internalLinkShort: ->

# This links out to MDN.
#
# Returns a {Number} greater than zero.
internalLinkLong: ->

Status Blocks

Classes and methods can be marked as Public, Private, or Internal.

You can flag multiple methods in a file with the following syntax:

### Public ###

That will mark every method underneath that block as Public. You can follow the same notion for Internal and Private as well.

You can have as many block status flags as you want. The amount of #s must be at least three, and you can have any text inside the block you want (for your own information). For example:

### Internal: This does some secret stuff. ###

If you explicitly specify a status for a method within a block, the status is respected. For example:

### Public ###

# Internal: A secret method
notShown: ->

shown: ->

shown is kept as Public because of the status block, while notShown is indeed Internal.

Delegation

If you're writing methods that do the exact same thing as another method, you can choose to copy over the documentation via a delegation. For example:

# {Delegates to: .delegatedRegular}
delegatedMethod: ->

# Public: I'm being delegated to!
#
# a - A {Number}
# b - A {String}
#
# Returns a {Boolean}
delegatedRegular: (a, b) ->

delegatedMethod has the same arguments, return type, and documentation as delegatedRegular. You can also choose to delegate to a different class:

# Private: {Delegates to: Another.Class@somewhere}
delegatedMethod: ->

Classes that are delegated should still set their own statuses. For example, even though Another.Class@somewhere is Public, delegatedMethod is still marked as Private. The same documentation remains.

Defaults

Unlike TomDoc, there is no additional notation for default values. Biscotto will take care of it for you, because it parses the CoffeeScript source and understands default values.

More Examples

For more technical examples, peruse the spec folder, which contains all the tests for Biscotto.

Generating and serving HTML

After installing Biscotto, you'll have a biscotto binary that can be used to generate the documentation recursively for all CoffeeScript files within a directory.

To view a list of commands, type

$ biscotto --help

Biscotto wants to be smart and tries to detect the best default settings for the sources, the README, any extra files, and the project name, so the above defaults may be different on your project.

Project defaults

You can define your project defaults by writing your command line options to a .biscottoopts file:

--name       "Biscotto"
--readme     README.md
--title      "Biscotto Documentation"
--private
--quiet
--output-dir ./doc
./src
-
LICENSE
CHANGELOG.md

Put each option flag on a separate line, followed by the source directories or files, and optionally any extra file that should be included into the documentation separated by a dash (-). If your extra file has the extension .md, it'll be rendered as Markdown.

Website keyboard navigation

You can quickly search and jump through the documentation by using the fuzzy finder dialog:

  • Open fuzzy finder dialog: Ctrl-T

In frame mode you can toggle the list navigation frame on the left side:

  • Toggle list view: Ctrl-L

You can focus a list in frame mode or toggle a tab in frameless mode:

  • Class list: Ctrl-C
  • Mixin list: Ctrl-I
  • File list: Ctrl-F
  • Method list: Ctrl-M
  • Extras list: Ctrl-E

You can focus and blur the search input:

  • Focus search input: Ctrl-S
  • Blur search input: Esc

In frameless mode you can close the list tab:

  • Close list tab: Esc

Gulp-Biscotto

If you want to use Biscotto with Gulp, see gulp-biscotto.

Metadata generation

You can use Biscotto to generate a complete JSON representation of your Node.js module. Simply pass in the --metadata flag and the path to your top-level module directory (where you keep your package.json).

biscotto --metadata ./path/to/module

Metadata generation should be considered an "advanced" way of using Biscotto. By generating metadata, Biscotto itself doesn't provide a way to turn it into HTML or interpret the comments in any way. It relies solely on the existing CoffeeScript AST. It allows for greater consumption and flexibility, however, because it traverses over the entire module.

You can find an example of the sort of metadata generated by looking at the test suite.

In (very) brief, take a look at this example:

"objects": {
  "3": {
    "0": {
      "type": "class",
      "name": "TextBuffer",
      "classProperties": [
        [
          4,
          10
        ]
      ],
      "doc": " Public: A mutable text container with undo/redo support and the ability to\nannotate logical regions in the text.\n\n ",
    }
  },
  "4": {
    "10": {
      "name": "prop2",
      "type": "primitive",
      "range": [
        [
          4,
          10
        ],
        [
          4,
          14
        ]
      ],
      "bindingType": "classProperty"
    }
  }
}

Items are indexed by their row numbers, followed by thier column numbers. The idea is that you can traverse all along the metadata blob by simply following the location references.

For a deeper understanding of the syntax and rationale, see the original proposal at issue #43

License

(The MIT License)

Copyright (c) 2014 Garen J. Torikian

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.



Biscotto

建立状态

Biscotto是生成 CoffeeScript 文档的工具。基础架构基于 codo ;但是,该项目使用了一个优秀的 TomDoc 符号的变体,而不是更详细的JSDoc。它还有更多的优点。

功能

  • 检测类,方法,常量,mixins&担心。
  • 生成一个不错的网站,以各种方式浏览代码文档。
  • 将JSON转换为任何输出的中间JSON输出
  • 可以生成更高级使用的元数据blob(请参阅下文了解更多信息

安装

npm install biscotto

使用TomDoc评论解析

API文档以 TomDoc 符号编写。最初设计为Ruby,TomDoc本身非常适合CoffeeScript。

与CoffeeScript匹配的解析规则有一些细微的变化。简单来说,这里列出如何格式化文档。

Visibility

每个类和方法应该从三个短语之一开始: Public: Internal: Private:。在文档生成过程中,您可以通过传入的选项来标记是否包含内部和私人成员。如果您没有这些状态指示器之一,则Biscotto将承担全局可见性(以下更多信息)。 / p>

# Public: This is a test class with inline.dot. Beware.
class TestClassDocumentation

Method arguments

每个方法参数必须以参数名称开头,后跟一个破折号( - ),而 参数的描述:

argument - Some words about the arg!

散列选项放在换行符上,以冒号开头:

options - These are the options:
          :key1 - Blah blah.
          :key2 - Blah
# Public: Does some stuff.
#
# something - Blah blah blah. Fah fah fah? Foo foo foo!
# something2 - Bar bar bar. Cha cha cha!!
# opts - The options
#        :speed - The {String} speed
#        :repeat -  How many {Number} times to repeat
#        :tasks - The {Tasks} tasks to do
bound: (something, something2, opts) =>

Examples

示例部分必须以Examples一词开头。下一行应为空白。之后的每一行都应该从初始注释标记中的两个空格缩进:

# A method to run.
#
# Examples
#
#  biscotto = require 'biscotto'
#  file = (filename, content) ->
#    console.log "New file %s with content %s", filename, content
#  done = (err) ->
#    if err
#      console.log "Cannot generate documentation:", err
#    else
#      console.log "Documentation generated"
#  biscotto.run file, done
run: ->

Return types

从方法返回时,您的行必须以 Returns 开头。您可以通过将不同行上的每个类型分开,以每个方法列出多个 Returns

# Private: Do it!
#
# Returns {Boolean} when it works.
returnSingleType: ->

# Internal: Does some thing. # # Returns an object with the keys: # :duration - A {Number} of milliseconds. returnAHash: =>

与TomDoc的偏离

GitHub Flavored Markdown

使用 GitHub Flavored Markdown 处理Biscotto文档。

Automatic link references

对于引用其他类,方法和混合的Biscotto注释被解析,并自动链接在一起。

支持多种不同的链接类型:

  • 正常的URL链接: {http://coffeescript.org/} [Try CoffeeScript](http://coffeescript.org/)
  • 链接到课堂或混音: {Animal :: Lion} [强大的狮子] {动物::狮子}
  • 直接链接到一个实例方法: {Animal.Lion :: walk} [The lion walking] {Animal.Lion :: walk}
  • 直接链接到一个类方法: {Animal.Lion.constructor} [新的国王诞生] {Animal.Lion.constructor}

如果你是指同一个类中的一个方法,可以省略类名: {:: walk} {。constructor} 。 >

另外,包装默认的JavaScript类型,如 {String} {Number} {Boolean} 等等。 - 将 MDN 自动生成的链接

以下是使用链接的示例:

# This links out to the long method of the same class.
#
# See {::internalLinkLong} for more info.
#
internalLinkShort: ->

# This links out to MDN. # # Returns a {Number} greater than zero. internalLinkLong: ->

Status Blocks

类和方法可以被标记为 Public, Private Internal

您可以使用以下语法在文件中标记多个方法:

### Public ###

这将把该块下的每个方法标记为 Public 。您也可以遵循与 Internal Private 相同的概念。

您可以拥有任意数量的块状态标志。 的数量必须至少为3个,您可以在所需块中有任何文本(为您自己的信息)。例如:

### Internal: This does some secret stuff. ###

如果您明确指定块中方法的状态,则该状态得到遵守。例如:

### Public ###

# Internal: A secret method notShown: ->

shown: ->

由于状态块被保留为Public,而 notShown 确实是Internal。

Delegation

如果您正在编写与其他方法完全相同的方法,则可以选择通过委托复制文档。例如:

# {Delegates to: .delegatedRegular}
delegatedMethod: ->

# Public: I'm being delegated to! # # a - A {Number} # b - A {String} # # Returns a {Boolean} delegatedRegular: (a, b) ->

delegatedMethod 具有与 delegatedRegular 相同的参数,返回类型和文档。您也可以选择委托不同的课程:

# Private: {Delegates to: Another.Class@somewhere}
delegatedMethod: ->

委派的类应该仍然设置自己的状态。例如,即使 Another.Class@somewhere 是Public, delegatedMethod 仍被标记为 Private 。相同的文件仍然存在。

Defaults

与TomDoc不同,缺省值没有其他符号。 Biscotto会为您处理,因为它解析了CoffeeScript源码并了解了默认值。

更多示例

有关更多技术示例,请仔细阅读包含Biscotto所有测试的 spec 文件夹。

生成和提供HTML

安装Biscotto后,您将有一个 biscotto 二进制文件,可用于递归地生成目录中所有CoffeeScript文件的文档。

要查看命令列表,请键入

$ biscotto –help

Biscotto想要聪明,并尝试检测源的最佳默认设置,README,任何额外的文件和 项目名称,因此上述默认值可能与您的项目不同。

项目默认值

您可以通过将命令行选项写入 .biscottoopts 文件来定义项目默认值:

–name       "Biscotto"
–readme     README.md
–title      "Biscotto Documentation"
–private
–quiet
–output-dir ./doc

./src

LICENSE CHANGELOG.md

将每个选项标志放在单独的行上,后跟源目录或文件,以及可选的任何额外的文件,该文件应该包含在由破折号( - )分隔的文档中。如果您的额外文件具有扩展名 .md ,则将其显示为Markdown。

网站键盘导航

您可以使用模糊查找器对话框快速搜索并浏览文档:

  • 打开模糊查找器对话框: Ctrl-T

在帧模式下,您可以在左侧切换列表导航框架:

  • 切换列表视图: Ctrl-L

您可以将框架对齐在框架模式中,或者以无框模式切换选项卡:

  • 类列表: Ctrl-C
  • Mixin列表: Ctrl-I
  • 文件列表: Ctrl-F
  • 方法列表: Ctrl-M
  • 其他列表: Ctrl-E

您可以对搜索输入进行对焦和模糊:

  • 重点搜索输入: Ctrl-S
  • 模糊搜索输入: Esc

在无框模式下,您可以关闭列表选项卡:

  • 关闭列表标签: Esc

Gulp-Biscotto

如果您想使用Biscotto与 Gulp ,请参阅 gulp-biscotto

元数据生成

您可以使用Biscotto来生成Node.js模块的完整JSON表示形式。只需传递 - 元数据标志和您的顶级模块目录的路径(您保留package.json的位置)。

biscotto –metadata ./path/to/module
元数据生成应被视为使用Biscotto的高级方式。通过生成元数据,Biscotto本身不提供将其转换为HTML或以任何方式解释注释的方法。它完全依赖于现有的CoffeeScript AST。但是,它允许更大的消耗和灵活性,因为它遍及整个模块。

您可以找到由查看测试套件生成的元数据类型的示例。

在(非常)简短的情况下,请看这个例子:

"objects": {
  "3": {
    "0": {
      "type": "class",
      "name": "TextBuffer",
      "classProperties": [
        [
          4,
          10
        ]
      ],
      "doc": " Public: A mutable text container with undo/redo support and the ability to\nannotate logical regions in the text.\n\n ",
    }
  },
  "4": {
    "10": {
      "name": "prop2",
      "type": "primitive",
      "range": [
        [
          4,
          10
        ],
        [
          4,
          14
        ]
      ],
      "bindingType": "classProperty"
    }
  }
}
项目按行号编号,后跟列号。这个想法是,您可以通过简单地跟随位置引用来遍历元数据blob。

为了更深入地了解语法和理由,请参阅问题#43 的原始提案

许可证

(麻省理工学院许可证)

版权所有(c)2014 Garen J. Torikian

任何人获得许可,免费授予 该软件和相关文档文件的副本( 软件),无限制地处理软件,包括 但不限于使用,复制,修改,合并,发布, 分发,再许可和/或出售本软件的副本,以及 允许提供软件的人员遵守 以下条件:

上述版权声明和本许可声明应为 包含在本软件的所有副本或大部分内容中。

该软件按原样提供,不提供任何形式的保证, 明示或默示,包括但不限于担保 适销性,特定用途适用性和非侵权性。 在任何情况下,作者或版权所有者均不承担任何责任 索赔,损害或其他责任,无论是在合同行为, 侵权行为或以其他方式引起的或与本协议相关的其他信息 软件或软件中的使用或其他交易。




相关问题推荐