NAV

Lade User Guide

Installing Lade

Lade depends on Node.js. Assuming you have Node, and your Node came with npm, you can install Lade using:

$ npm install -g Lade

For those new to npm, -g indicates that you want Lade installed as globally in your environment. You may need to prefix the command with sudo, depending on how you installed node.

Documenting Programs

Lade extracts comments from source code, and writes the comments to a given target file.

An example follows.

Suppose you have a hello.coffee file with the following contents.

# ---
# target: hello.md
# ---
# # Hello, World!
#
# A "Hello, World!" program is a computer program that outputs or
# displays "Hello, World!" to the user. Being a very simple program in
# most programming languages, it is often used to illustrate the basic
# syntax of a programming language for a working program.
#
# This implementation uses Coffescript.
print "Hello, World!"

You can use Lade to extract the documentation to a hello.md file. The hello.md file will contain the following.

# Hello, World!

A "Hello, World!" program is a computer program that outputs or
displays "Hello, World!" to the user. Being a very simple program in
most programming languages, it is often used to illustrate the basic
syntax of a programming language for a working program.

This implementation uses Coffescript.

You can also document for different audiences in the same source file. For example, if the hello.coffee file contained the following.

# ---
# target: hello_for_users.md
# ---
# # Hello, World!
#
# A "Hello, World!" program is a computer program that outputs or
# displays "Hello, World!" to the user. Being a very simple program in
# most programming languages, it is often used to illustrate the basic
# syntax of a programming language for a working program.
#
# Run this "Hello, World!" using the command `coffee hello.coffee`.

# ---
# target: hello_for_programmers.md
# ---
# # Hello, World!
#
# The implementation of "Hello, World!" in Coffeescript is very
# simple. It consists of a single file containing a single statement.
#
# Refer to the `hello.coffee` file for the source of this
# documentation and the program itself.
console.log "Hello, World!"

Then Lade would produce two separate documentation files. The hello_for_users.md file would contain the following.

# Hello, World!

A "Hello, World!" program is a computer program that outputs or
displays "Hello, World!" to the user. Being a very simple program in
most programming languages, it is often used to illustrate the basic
syntax of a programming language for a working program.

Run this "Hello, World!" using the command `coffee hello.coffee`.

And the hello_for_programmers.md file would contain the following.

# Hello, World!

The implementation of "Hello, World!" in Coffeescript is very
simple. It consists of a single file containing a single statement.

Refer to the `hello.coffee` file for the source of this
documentation and the program itself.

Using Lade

To extract documentation, just point lade to source files that you want docs for:

$ lade *.coffee

Lade will also handle extended globbing syntax if you quote arguments:

$ lade "lib/**/*.coffee" README.md

By default, lade will put extracted documentation in a doc subfolder of your project.

Configuring Lade

Lade can configure itself from a file as an alternative to using command-line arguments.

Create a .lade.json file in your project root, where each key maps to an argument you would pass to the lade command. File names and globs are defined as an array with the key glob. For example:

{
    "glob": [
        "**/*.md",
        "**/*.coffee",
        ".lade.json",
        "package.json"
    ],
    "except": [
        "node_modules/**"
    ],
    "out": "./doc"
}

If you invoke lade without any arguments, it will use your pre-defined configuration.

Command Line Usage

--help: Command line usage

--glob: A file path or globbing expression that matches files to generate documentation for.

--except: Glob expression of files to exclude. Can be specified multiple times.

--out: The directory to place generated documentation, relative to the project root [./doc]

--root: The root directory of the project.

--languages: Path to language definition file.

--silent: Output errors only.

--version: Shows you the current version of lade

--verbose: Output the inner workings of lade to help diagnose issues.

--very-verbose: Hey, you asked for it.

Source File Types

Lade can extract documentation from the following source file types: