• This repository has been archived on 25/Mar/2019
  • Stars
    star
    105
  • Rank 328,196 (Top 7 %)
  • Language
    CoffeeScript
  • License
    MIT License
  • Created over 11 years ago
  • Updated over 9 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

UNMAINTAINED. CoffeeScript API documentation tool that uses TomDoc notation.

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.

More Repositories

1

html-pipeline

HTML processing filters and utilities
Ruby
2,250
star
2

html-proofer

Test your rendered HTML files to make sure they're accurate.
Ruby
1,574
star
3

markdowntutorial.com

Lessons to help guide new writers into Markdown!
HTML
515
star
4

commonmarker

Ruby wrapper for the comrak (CommonMark parser) Rust crate
Rust
429
star
5

Earthbound-Battle-Backgrounds-JS

A JavaScript project that generates all the Earthbound/Mother 2 backgrounds.
JavaScript
338
star
6

jekyll-last-modified-at

A Jekyll plugin to show the last_modified_at time of a post.
Ruby
219
star
7

isBinaryFile

Detects if a file is binary in Node.js. Similar to Perl's -B
TypeScript
161
star
8

mathematical

Convert mathematical equations to SVGs, PNGs, or MathML. A general wrapper to Lasem and mtex2MML.
Ruby
155
star
9

Shelves

An Android application that manages your collection of apparel, board games, books, comics, gadgets, movies, music, software, tools, toys, and video games.
Java
110
star
10

addalicense.com

DEPRECATED: Add a license to your public GitHub repositories
JavaScript
85
star
11

jekyll-time-to-read

A liquid tag for Jekyll to indicate the time it takes to read an article.
Ruby
72
star
12

nak

ack and ag inspired tool written in Node. Designed to be fast.
JavaScript
69
star
13

tailwind_merge

Utility function to efficiently merge Tailwind CSS classes without style conflicts.
Ruby
69
star
14

extended-markdown-filter

Some additional Markdown formatting, for use in HTML::Pipeline
Ruby
54
star
15

jekyll-html-pipeline

Use GitHub's HTML::Pipeline, in Jekyll!
Ruby
50
star
16

selma

Selma selects and matches HTML nodes using CSS rules. Backed by Rust's lol_html parser.
Rust
46
star
17

repository-sync

Simple Sinatra server to keep two repositories in sync (not like the band)
Ruby
45
star
18

ooo-maker

Modify your GitHub avatar to let people know you're away!
JavaScript
41
star
19

Earthbound-Battle-Backgrounds

This is a live wallpaper for Android 2.1+ that shows the battle background animations from Earthbound (Mother 2).
Java
38
star
20

roaster

Turns a raw and crunchy Markdown file into nice and smooth output
CoffeeScript
30
star
21

panda-docs

Pretty Awesome (and Necessary) Documentation Assembly--A total documentation build system for technical writers, and those who want to be like them.
JavaScript
29
star
22

no-more-masters

Rename your default Git branch from master to production
JavaScript
26
star
23

mtex2MML

A Bison grammar to convert TeX math into MathML.
C
24
star
24

graphql-idl-parser

A parser for the GraphQL IDL format.
Rust
24
star
25

panino-docs

API documentation generation tool with an emphasis on JSDoc-style comment parsing
JavaScript
22
star
26

publisher

Publishes your non-Jekyll content in `master` directly to `gh-pages`.
Ruby
19
star
27

ColoredLogcatPlusPlus

An extension of Jeff Sharkey's excellent ColoredLogcat terminal hack for Android development. Supports colors and filtering!
Python
17
star
28

jekyll-config-variables

A Jekyll monkey-patch to allow you to use variables within your _config.yml file.
Ruby
15
star
29

jekyll-conrefifier

Allows you to use Liquid variables in various places in Jekyll
Ruby
14
star
30

what_you_say

Natural language detection library. Written in Rust, wrapped in Ruby.
Ruby
13
star
31

namp

A fork of chjj's marked that adds some additional features
JavaScript
12
star
32

heroku_chat_sample

Go
11
star
33

NotoColorEmoji-png

A conversion of Android KitKat's NotoColorEmoji.ttf into PNG images
11
star
34

nothingherebut.me

A vanishing story.
JavaScript
10
star
35

color-proximity

Match the threshold of a color against a collection of colors.
Ruby
9
star
36

mathematical-node

A Node.js port of Mathematical
HTML
8
star
37

robotstxt-parser

Another fork of the robotstxt gem
Ruby
8
star
38

pointillist

A Ruby library to convert Atom's stylesheets into Pygments-compatible HTML
C
8
star
39

functional-docs

A documentation test suite for HTML files.
JavaScript
7
star
40

jekyll-geo-pattern

A liquid tag for Jekyll to generate an SVG/Base64 geo pattern
Ruby
6
star
41

function-extractor

Extracts all the functions from a Javascript file into an array of objects.
JavaScript
6
star
42

graphql-idl-parser-ruby

A parser for the GraphQL IDL format.
Ruby
6
star
43

branta

Search, for GitHub Pages.
Ruby
6
star
44

markdown_conrefs_js

Support for content references (conrefs) in Markdown (for Javascript).
JavaScript
6
star
45

notext.news

The news without the words
JavaScript
5
star
46

wireless-snes

Arduino sketches to intercept controller data from one SNES console and send it to another.
C++
5
star
47

destroy-all-monuments

This is data taken from the SPLC report titled "Whose Heritage? Public Symbols of the Confederacy" from April 21, 2016
Ruby
5
star
48

jekyll-jsminify

A very simple way to minify your JavaScript and CoffeeScript content in Jekyll.
Ruby
4
star
49

task-lists-js

An implementation of the basic task list logic (in CoffeeScript)
HTML
3
star
50

jekyll-toc-helpers

Some helper tags for generating TOCs.
Ruby
3
star
51

nanoc-redirector

A redirection extension for Nanoc
Ruby
3
star
52

past.codes

Remember the repositories you starred on GitHub.
Ruby
3
star
53

dotfiles-old

My dotfiles.
Shell
3
star
54

heroicons_helper

Heroicons port for Ruby
Ruby
3
star
55

nanoc-conref-fs

A Nanoc filesystem to permit using conrefs/reusables in your content.
Ruby
3
star
56

sffsoccer2ical

Converts the SFF soccer schedule to an ics file
Ruby
3
star
57

documentation-renderer

Documentation tools for Atom and Chrome
CoffeeScript
2
star
58

Shmup-for-Android

An Android port of an iOS Shmup.
D
2
star
59

ecma-re-validator

Validate a regular expression against what ECMA-262 (JavaScript) can actually do.
Ruby
2
star
60

mathematical-rs

Convert MathML into SVG.
Rust
2
star
61

page-toc-filter

A filter for the HTML::Pipeline to generate a page's table of contents.
Ruby
2
star
62

april-24-2015

Ruby
2
star
63

helpmewith.money

HTML
2
star
64

shale

JavaScript
2
star
65

math-to-itex

Parse a string and convert math equations to the itex notation.
Ruby
2
star
66

slack-pokemon-emoji

This is a tool to help you generate Pokรฉmon for your Slack team.
Ruby
2
star
67

changecase_rb

Demo showcasing wrapping Rust in Ruby (RubyConf 2023)
Ruby
2
star
68

kraken

Earthbound's battle backgrounds (as a screensaver)
C#
2
star
69

ADC-Zipcode-Sorter

Takes a CSV file, then sorts the zip codes in that file according to the USPS ADC rules
PHP
2
star
70

sfdc_grpc_api

JavaScript
1
star
71

who-owes-what

TypeScript
1
star
72

jekyll-collection-multiplier

Ruby
1
star
73

fake-pages-site

1
star
74

crud-test

A repository for people to ogle over.
1
star
75

rss-to-tweet

Ruby
1
star
76

colorpicker

A native colorpicker, for Atom.
CSS
1
star
77

tabulalingua

A table. For languages.
JavaScript
1
star
78

atweetforeveryoccasion.com

Tweets are considered official presidential statements; let's contrast 45's communication against his hypocritical actions.
CSS
1
star
79

escapist

Extremely minimal HTML/`href` escaping/unescaping. Emphasis on minimal.
Rust
1
star
80

tweetstorm

CLI tool to make a tweetstorm, with replies to yourself.
Ruby
1
star
81

ace

Ace (Ajax.org Cloud9 Editor)
JavaScript
1
star
82

graffito

JavaScript
1
star
83

YALC

Yet another link checker. This one only checks local files.
Perl
1
star
84

render-html-from-ast

Internal API renderer used by panino and cannolo
JavaScript
1
star
85

jekyll-github-markup

Ruby
1
star
86

jekyll-mathematical

A Jekyll plugin that wraps around Mathematical
Ruby
1
star
87

bartleby

JavaScript
1
star
88

focus_concentrate

Get close. Stay centered. Don't move.
HTML
1
star
89

heroku-buildpack-pango

Heroku buildpack with Pango
Shell
1
star
90

metrocarddump

This program will dump all of your EasyPay MTA rides into a JSON file.
Go
1
star
91

rubocop-standard

Grouped Rubocop rules
Ruby
1
star
92

token_checksum

Generate a 30 character long random token, with a prefix and a 32-bit checksum in the last 6 digits.
Ruby
1
star