micmath/jsdoc — pull request #72 by rafalwrzeszcz (2011-12-15 15:39:50+00:00)
Title: Tutorials

Tutorials mechanism. It's a bit similar to phpDocumentor's one.

With `-u` option you can specify a directory, which JSDoc will search for tutorials. It will treat any file with extension .xml, .xhtml, .html and .htm as tutorial content files. Also .md and .markdown extensions are supported and will be additionaly parsed as Markdown and converted to HTML.

By default each tutorial is top-level. Top-level tutorials are listed in navigation menu.

# Configuration

Each tutorial file can have additional .js/.json file (with same name, just different extension) which will hold additional tutorial configuration. Two fields are supported:

* `title` overrides display name for tutorial with the one specified in it's value (default title for tutorial is it's filename).
* `children` which holds list of sub-tutorials identifiers.

When tutorial has `children` property set, it's children will be listed in it's *ToC* as sub-articles instead of top-level navigation menu.

# Identifiers

Tutorial is identified by it's filename (eg. `test.html` is named `test`). No matter to what you will change tutorial's title, it's identifier will be just `test`. Title is for displaying, name is for identifying. This allows you to link to tutorial without depending on it's variable display name.

# @tutorial tag

Doclets can have assigned tutorials (similar to @link and @see tags) through @tutorial tag:

```javascript
/**
* Description.
*
* @class
* @tutorial test-tutorial
*/
```

@tutorial tag can also be handled in-line in descriptions:

```javascript
/**
* Description {@tutorial test-tutorial}.
*
* @class
*/
```

# Tutorial content

Tutorial content is precessed with `resolveLinks()`, which means you can use both `{@link}` and `{@tutorial}` tags within tutorial text! They will be processed just like doclets descriptions.

```html

This is tutorial content. See {@link Class.create} for OOP info and {@tutorial class-create} tutorial.

```

# Backward compatibility

It is purely additional feature - if one won't specify `-u` option it won't affect documentation building. Also template `publish()` method is not a problem, since tutorials are passed as last argument, so if template function is not prepared for tutorials it just won't process them.

# Alternative approach

I was wondering if maybe new doclet kind (kind: "tutorial", which would act as namespace) would be introduced for this feature, but I found it too different. But if someone finds it interesting, try to reorganise.