Ludwig Documentation Generator

lwdoc is the Ludwig Documentation Generator. This guide details lwdoc usage, arguments, options, and examples.

Usage

lwc <PATH> [options]

Arguments

<PATH>
Input file or directory

Options

-h | --help
Show help text.
-i | --include-dirs <DIR1:DIR2>
Add additional search directories for modules.
-o | --output-dir <ARG>
Set directory for resulting HTML files.
-b | --base-dir <ARG>
Set a directory as the project root.
-r | --recursive
Recursively search for .lw files.
-f | --format {html | markdown | xml}
Set output format. Use html for HTML output (default), markdown for Markdown output, and xml for XML output.

Definition

lwdoc is a documentation generation tool for Ludwig. You can annotate Ludwig code with Markdown, and lwdoc will generate HTML describing your libraries.

lwdoc is part of the Fugue Client Tools.

Examples

Writing Documentation

To create lwdoc documentation, first annotate the Ludwig by writing comments inside the Ludwig file. Read the comments in the module below to learn how. To see lwdoc in action, you can download this module here and generate an HTML file of the documentation by following the instructions in Running lwdoc To Generate Documentation.

# You can add documentation about a module by starting the file with a
# comment block, like this one. It's important that the `#` character
# is the *very first* character of the file.
#
# This is a second paragraph of documentation. As you can see, the
# line in between the paragraphs isn't "empty"; it starts with an `#`
# character. This is important, as otherwise it wouldn't be considered
# one "block" of documentation.
#
# You can use Markdown to add some formatting to the documentation.
#
# - Bullet lists
# - *Italicized text*
# - **Bold text**
# - `Inline code`
#
# For more information, refer to a Markdown guide, such as [this
# one](https://daringfireball.net/projects/markdown/syntax).

# You can document a binding by adding a comment above it. This line
# documents the `my-int` binding. Note that when a single word is
# marked by backticks *and* that word is a binding or type defined in
# the composition, `lwdoc` generates a link to that binding.
Int my-int: 1

# A type can also be documented. This comment is the main description
# of the type `Person`. Lines starting with `@field`, followed by the
# name of the field, document the different fields.
#
# @field name The name of the person.
# @field age The age of the person.
type Person:
    name: String
    age: Int

# This is a point on a 2-D plane.
#
# @field x Sometimes a field can have a really long and complicated
# description.
#
# In that case, you can use multiple paragraphs. This is part of the
# `x` description.
#
# @field y This field is much shorter.
type Point:
    x: Int
    y: Int

# A sum type also has a main description.
#
# @constructor Lettuce Leafy green vegetable
# @constructor Swiss-cheese Popular cheese
# @constructor Bacon Cured meat product
#
# Note that you can still have multiple paragraphs for these. This is
# part of the bacon description.
#
# @constructor Tomatoes Sweet garden vegetable
type Topping:
    | Lettuce
    | Swiss-cheese
    | Bacon
    | Tomatoes

# This is another sum type. We illustrate here that we can also document
# fields of constructors.
#
# @field topping We can start by documenting the topping field here,
# since it is shared by all constructors.
#
# @constructor Basic-sandwich We can put some info about a basic
# sandwich here. It's a sandwich with only a single topping.
#
# @constructor Deluxe-sandwich A deluxe sandwich has an extra topping.
#
# @field extra-topping Since this field belongs to Deluxe-sandwich
# specifically, we need to put it below that constructor.
type Sandwich:
    | Basic-sandwich
        topping: Topping
    | Deluxe-sandwich
        topping: Topping
        extra-topping: Topping

# Another documented binding.
Sandwich my-sandwich: Deluxe-sandwich {
    topping: Swiss-cheese,
    extra-topping: Bacon
}

# This is a function binding. Function bindings can have additional `@arg`
# and `@return` documents.
#
# @arg toppings How many toppings to add.
# @arg favorite Your favorite topping.
# @return A customized sandwich.
fun sudo-make-me-a-sandwich {
  toppings: Int,
  favorite: Topping
} -> Sandwich:
    case toppings of
        | 1 -> Basic-sandwich {topping: favorite}
        | _ -> Deluxe-sandwich {topping: favorite, extra-topping: favorite}

Running lwdoc To Generate Documentation

To generate HTML files from the annotations in your Ludwig file, use the following command, replacing MyComposition.lw with the name of your composition:

lwdoc WritingDocumentation.lw

You’ll see the following output:

lwdoc'd WritingDocumentation -> WritingDocumentation.html

Documentation files are generated in the same directory as the source file. If you prefer to generate Markdown or XML files instead of HTML, use the -f or --format option:

lwdoc -f markdown WritingDocumentation.lw
lwdoc -f xml WritingDocumentation.lw