[Cordova Wiki] Update of "DocumentationCLIDesign" by MichaelBrooks

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "DocumentationCLIDesign" page has been changed by MichaelBrooks:
http://wiki.apache.org/cordova/DocumentationCLIDesign

Comment:
Add initial docs design

New page:
= Hastings =

 Apache Cordova Documentation CLI Tool

<<TableOfContents(3)>>

== Install ==

 {{{$ npm install hastings}}}

== Usage ==

 {{{$ hastings [path] ................. output written to /build/doc/}}}

 {{{$ hastings < path ................. output written to stdout}}}

 {{{$ hastings watch [path] ........... build and watch for changes}}}

 {{{$ hastings init [path] ............ initialize default doc files}}}

 {{{$ hastings create template file ... create a template doc file}}}

 {{{$ hastings help ................... get help}}}

== Simple Usage ==

 {{{# build files in doc/}}}

 {{{$ hastings}}}

 {{{    => build/doc/}}}

== Detailed Usage ==

 {{{# initialize default doc file structure}}}

 {{{$ hastings init}}}

 {{{    => mkdir doc/}}}

 {{{    => mkdir doc/en/}}}

 {{{    => touch doc/en/index.md}}}

 {{{    => mkdir lib/doc/}}}


 {{{# create a getting started guide}}}

 {{{$ hastings create guide doc/en/getting-started.md}}}


 {{{# live preview of documentation}}}

 {{{$ hastings watch}}}

 {{{    => [2012-06-08 11:13am] server started at 127.0.0.1:3000}}}

 {{{    => [2012-06-08 11:13am] serving build/doc/}}}

 {{{    => [2012-06-08 11:13am] rendered doc/en/getting-started.md}}}

== Commands ==

=== $ hastings [path] ===

Builds the HTML documentation and outputs the files.

 {{{$ hastings}}}

 {{{$ hastings doc/}}}

 {{{$ hastings documentation/}}}

By default, the documentation path is `doc/`. This can be overridden with
`[path]`.

The optional `[path]` can be a markdown file or directory. When a file is
specified, it is rendered to the the build path. When a directory is specified,
then the entire directory is copied to the build path and each markdown file
is replaced with a HTML file.

The build output is stored in `build/doc`.

=== $ hastings < path ===

Builds the HTML documentation and pipes output to the console.

 {{{$ hastings < doc/}}}

 {{{$ hastings < documentation/}}}

 {{{    => [outputs a wad of HTML]}}}

The parameter `path` can be a markdown file or directory.

=== $ hastings watch [path] ===

Live edit and preview of the documentation.

 {{{$ hastings watch}}}

 {{{$ hastings watch doc/}}}

 {{{$ hastings watch documentation/}}}

 {{{    => [2012-06-08 11:13am] server started at 127.0.0.1:3000}}}

 {{{    => [2012-06-08 11:13am] serving build/doc/}}}

 {{{    => [2012-06-08 11:13am] rendered doc/en/index.md}}}

By default, the documentation path is `doc/`. This can be overridden with
`[path]`.

The optional `[path]` can be a markdown file or directory. When a file is
specified, it is rendered to the the build path. When a directory is specified,
then the entire directory is copied to the build path and each markdown file
is replaced with a HTML file.

The build output is stored in `build/doc` and can be viewed by opening a browser
to `localhost:3000`.

=== $ hastings init [path] ===

Initializes a default documentation file structure. This structure is not
required.

 {{{$ hastings init}}}

 {{{    => mkdir doc/}}}

 {{{    => mkdir doc/en/}}}

 {{{    => touch doc/en/index.md}}}

 {{{    => mkdir lib/doc/}}}

By default, the markdown documentation is stored is `doc/` and library files
are stored in `lib/doc/`. You are welcome to change the documentation path to
match your naming convention but you will then need to specify the `path` to
each command.

=== $ hastings create ''template'' ''file'' ===

Create a new document from a template.

 {{{$ hastings create guide doc/en/getting-started.md}}}

The `template` argument is the type of template to use. There are four templates
bundled with hastings:
 * `api`
 * `guide`
 * `trouble-shooting`
 * `faq`

The `file` argument is the file to be created.

You are not required to use templates. Although, templates help you to write
documentation quicker and more consistently.

Custom templates can be added to `lib/doc/template/`. The
Customization section explains templates in more detail.

=== $ hastings help ===

Display the commands available to hastings.

 {{{$ hastings help}}}

== Customization ==

=== Templates ===

You can add custom templates and override the existing ones.

Add any markdown file to `lib/doc/template/` and the filename is used as the
template name.

For example you can make `lib/doc/template/getting-started.md` as a
Getting Started template. You can then create a document from the template
with the command:

 {{{$ hastings create getting-started doc/hello-world.md}}}

You can override a default template by create a file in `lib/doc/template/`
with the same name. For example, to override `guide` you can create the file
`lib/doc/template/guide.md`.

=== Themes ===

You can add a custom HTML theme for your documentation.

Add a HTML theme to `lib/doc/theme/` and it will override the default theme.
When building your documentation, the entire theme directory is copied to
`build/doc/`.

`index.html` is your HTML theme template. Add the element `<hastings/>`
where you want the content of each markdown file to be inserted.

 {{{<html>}}}

 {{{    <head>}}}

 {{{        ...}}}

 {{{    </head>}}}

 {{{    <body>}}}

 {{{        ...}}}

 {{{        <hastings type="content"/>}}}

 {{{        ...}}}

 {{{    </body>}}}

 {{{</html>}}}