Selleck User Guide

Selleck is a tool for generating user documentation from Mustache-based templates. It was created to generate documentation for the YUI Library. At the moment this document and Selleck itself are pretty YUI-specific, but over time Selleck will become a more generic tool, and the YUI-specific parts of the workflow (and this document) will be broken out.

Requirements

Selleck requires Node.js 0.4.0 or greater. It also requires a few third-party dependencies, but these will be installed automatically by npm.

Installation

Install Selleck using npm:

$ npm install selleck -g

The current stable version of Selleck is: 0.1.18

Or clone the GitHub repo to install the latest development version:

$ git clone git://github.com/yui/selleck.git
$ cd selleck && npm install -g

Running the tests

Selleck tests are written in vows.

$ git clone git://github.com/yui/selleck.git
$ cd selleck && npm install
$ npm test

Developing with Selleck can be done easily with npm link.

$ git clone git://github.com/yui/selleck.git
$ cd selleck
$ sudo npm link

After linking, you can edit the code in the repo and use the global selleck command on other projects for testing.

Build Status

Each push to Github results in a Travis-CI build. Current build status:

Overview

Selleck pages are .mustache files that can contain HTML markup, Mustache templating tags, and Selleck-specific markup (described below).

The Mustache Manual describes the Mustache template language. If you haven't used Mustache before, you may want to read the manual before continuing.

Projects & Components

Selleck documentation typically takes the form of one top-level project with zero or more components. These are represented by directories containing various files and subdirectories that follow a few conventions.

Pages

Each project or component may have multiple pages. An index.mustache page is required, and any number of other .mustache pages may also be provided in the same directory. These will be transformed into .html files in the generated output.

Partials & Layouts

Partials and layouts are special Mustache templates that live in the partials/ and layouts/ directories under a project or component directory.

A partial can be included in any page simply by referring to it by name using a special Mustache tag. For example, the tag {{>footer}} would include a partial named footer.mustache.

A layout is like a wrapper for other pages. A layout named main.mustache will be used by default to wrap all pages, if it exists. A layout named component.mustache will be used to wrap all component pages; if no component layout exists, then component pages will use the main layout. Inside the layout, the special partial tag {{>layout_content}} will be replaced with the page content.

Components will automatically inherit any available partials and layouts from their parent project. If both a project and a component have a partial or layout with the same name, the component's will take precedence at the component level, while the project's will take precedence at the project level.

Metadata

Projects and components have metadata files (project.json for projects, component.json for components) containing data that will be made available to page templates.

Project metadata files must contain a projectName property, and component metadata files must contain a name property; otherwise, the contents of these files are freeform. You can use these files to provide data to your templates, which you can then refer to using Mustache tags like {{projectName}}.

`project.json` sample

{
    "projectName": "YUI 3",
    "yuiVersion" : "3.3.0",
    "yuiSeedUrl" : "http://yui.yahooapis.com/combo?3.3.0/build/yui/yui-min.js&3.3.0/build/loader/loader-min.js"
}

`component.json` sample

{
    "name"       : "autocomplete",
    "displayName": "AutoComplete",
    "description": "Provides automatic input completion or suggestions for text input fields and textareas.",
    "author"     : "rgrove",

    "tags": ["widget", "autocomplete"],
    "use" : ["autocomplete"]
}

Static Assets

Finally, projects and components may provide an assets/ directory containing static assets such as CSS and JavaScript. The assets directory will be copied directly to the output folder for the project or component in question, so its assets can be referenced via relative URLs.

Directory Structure

The following table describes the required and optional contents and structure of a project or component documentation directory.

File/Directory	Description
`assets/`	Optional. Directory containing static assets (such as images, JavaScript, and CSS) used by the documentation. This directory and its contents will be copied to the output directory. If an `assets/` directory already exists under the output directory, it will be deleted to make way for the new one. Component assets are copied to subdirectories of the main assets directory, named according to the value of the `name` property in the component's metadata.
`layouts/`	Optional. Directory containing layouts. A layout is a template that will be wrapped around other pages. A layout named `main.mustache` will be used for all pages, while a layout named `component.mustache` will be used for components (components will fall back to `main.mustache` if `component.mustache` is not found). Inside a layout, the tag `{{>layout_content}}` will be replaced with page content.
`partials/`	Optional. Directory containing partials. A partial is a `.mustache` file that can be included in another documentation page using a directive like `{{>partial-name}}`, where `partial-name` is the name (minus extension) of the partial file (e.g. `partial-name.mustache`).
`component.json`	Required for components. JSON file containing metadata which will be made available to documentation templates. The metadata is freeform, but must contain at least a `name` property which contains the name of the component. This name will be used as the name of the component's output directory, among other things.
`project.json`	Required for projects. Works just like component metadata; the only difference is that the project metadata must contain a `projectName` property.
`index.mustache`	Required. Main Mustache template for the project or component. This will be parsed and generated as `index.html` in the output directory.

In addition to the files listed here, the documentation directory may contain any number of .mustache files. These will be parsed and generated as .html files in the output directory.

Automatic Table of Contents Generation

If a Selleck template includes the placeholder {{toc}}, Selleck will automatically parse HTML headings at level 2 and up (<h2>, <h3>, etc.) in the page and will replace the {{toc}} placeholder with a generated table of contents. The table of contents on this very page was generated this way.

Headings that don't already have id attributes will be given generated ids based on the heading text, so <h2>Sample Heading</h2> would become <h2 id="sample-heading">Sample Heading</h2>.

To exclude a heading from the table of contents, add the class name no-toc, like this:

<h2 class="no-toc">Secret Heading</h2>

Markup Reference

In addition to Mustache templating tags, Selleck provides some markup syntax of its own to make things like escaping code blocks and creating links easier. The following markup is supported in all Selleck pages, layouts, and partials.

Name	Example	Description
Code block	``` YUI().use('node', function (Y) { // Sample code }); ```	Three backticks on a line by themselves indicate the beginning or end of a block of code. Text inside the block will be HTML-escaped, syntax-highlighted, and wrapped in a `<pre>` tag. The wrapped text is automatically unindented to match the indentation level of the first line, so you're free to indent the containing block itself however you want. You may optionally explicitly specify a language to use for the syntax highlighting immediately after the opening triple-backticks. For example: ```handlebars
Code (inline)	`<code>`	Text between ` characters is HTML-escaped and then wrapped in `<code>` tags. To output a literal ` character, escape it with a backslash: \`
Link (internal)	[[#Heading Name]] [[#Heading Name\|Optional Link Text]]	Creates a link to the specified heading (where `Heading Name` is the text inside a heading tag somewhere on the page, such as `<h2>Heading Name</h2>`). By default, the heading name is used as the link text. If optional custom link text is provided, that will be used instead.
Literal delimiters	\{{foo\}}	Escape a Mustache left or right delimiter with a `\` to tell Selleck it should output the delimiter characters as is rather than treating them as Mustache delimiters. This is particularly useful when writing documentation about Mustache in Mustache!
Preformatted block (no highlighting)	```nohighlight This is just a normal preformatted text block with no highlighting. ```	Just like a code block, but without any syntax highlighting.
Terminal block	```terminal $ sudo -i # rm -rf / ```	Like a code block, but for displaying sample input and output for a command line terminal. Shell prompts at the beginnings of lines (`$` or `#`) will be made non-selectable for easier copying and pasting.

Command Line Usage

After installation, you'll have a new command line application named selleck. Run selleck -h for a summary of the options Selleck supports.

If no options are given, Selleck will search the current directory and all its subdirectories recursively, looking for documentation directories (it does this by searching for project.json and component.json files). It will generate HTML documentation from all the doc directories it finds, and will write the generated docs to ./docs by default.

$ cd ~/src/yui/yui3
$ selleck
[info] Generating project docs for /Users/rgrove/src/yui/yui3/src/common/docs
[info] Generating component docs for /Users/rgrove/src/yui/yui3/src/autocomplete/docs
[info] Generating component docs for /Users/rgrove/src/yui/yui3/src/history/docs
[info] Done! Docs were written to: ./docs

To generate documentation from a directory other than the current directory, pass the directory as an argument.

$ selleck ~/src/yui/yui3

You may also optionally specify an output directory for the generated docs.

$ selleck ~/src/yui/yui3 --out ~/src/yui/yui3/docs

To specify a documentation theme other than Selleck's default theme, use the --theme option/

$ selleck ~/src/yui/yui3 --theme /path/to/theme

To generate documentation for an explicit project rather than searching for the project, use the --project option.

$ selleck --project /path/to/project

Finally, the --server option will start a web server that you can use to preview your documentation in real time as you make changes, so that you don't need to regenerate after every change. It can be used in combination with any of the other options.

$ selleck ~/src/yui/yui3 --server
[info] Selleck is now giving Ferrari rides at http://localhost:3000

Other Stuff

Selleck isn't finished yet, and there's still more to document here. For now, poke around the default template and some of the component doc directories in the YUI 3 source tree to see what's possible.

License

Redistribution and use of this software in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Yahoo! Inc. nor the names of Selleck's contributors may be used to endorse or promote products derived from this software without specific prior written permission of Yahoo! Inc.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.