hoe-manualgen

Introduction

This is a manual for hoe-manualgen. Hoe-manualgen is a plugin for Hoe, a Rake/Rubygems helper for project Rakefiles. It adds tasks for creating, rendering, and uploading a technical manual or cookbook for your project.

Installation

You can install the plugin via Rubygems in the usual manner:

$ sudo gem install hoe-manualgen

After it’s installed, you can enable it in your Hoe-ified Rakefile for access to the manual-generation tasks:

require 'hoe'

Hoe.plugin :manualgen

Hoe.spec 'my-project' do
	# ...
end
Enable the ‘manualgen’ plugin in your Rakefile

Rake Tasks

If you don’t already have a manual for your project, the plugin only defines one task called manual, which will set up a basic manual directory structure in your project. You can execute it by running rake manual:

$ rake manual
(in /Users/jrandom/source/ruby/my-project)
Create a new manual directory tree from a template? [n] y
Generating manual skeleton
[...]
Creating the manual directory-structure.

It creates a directory called ‘manual’ (by default) at the root of your project and copies some default resources, templates, and filters into it. It also generates a minimal index page for your new manual to get you started at manual/src/index.page. It looks something like this:

---
title: Introduction
layout: default
tagline: I'm a tagline!
index: 1
filters:
  - erb
  - links
  - examples
  - textile
---

h2. Introduction

<div id="auto-toc"></div>

This is a manual for my-project. It's not done yet.

h3. Authors

* J. Random Hacker


h3. License

Copyright (c) 2011, J. Random Hacker
All rights reserved.

Redistribution and use 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 the authors nor contributors may be used to endorse or promote products
  derived from this software without specific prior written permission.

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.

<div id="cc-license">
<a rel="license" href="http://creativecommons.org/licenses/by/3.0/">
	!http://i.creativecommons.org/l/by/3.0/88x31.png(Creative Commons License)!
</a><br/>
The content of this manual, including images, video, and any example source code is 
licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative 
	Commons Attribution 3.0 License</a>.
</div>
The initial index page.

With an existing manual directory structure, the manual task will render the manual, so you can actually render the basic index page right after setting it up:

$ rake manual:rebuild
(in /Users/mgranger/source/ruby/hoe-manualgen)
rm -f manual/output/index.html
Copying manual resources
Parsing sources...
100% [ 1/ 1]  lib/hoe/manualgen.rb                                              

Generating Darkfish...

Files:         1
Classes:       5 (    0 undocumented)
Constants:    17 (    9 undocumented)
Modules:       2 (    1 undocumented)
Methods:      30 (    0 undocumented)
 81.48% documented

Elapsed: 0.8s
cp -r doc manual/output/api
  manual/src/index.page -> manual/output/index.html
Generating the manual.

As you can see, the task generates the API documentation, copies it into a subdirectory, then renders each .page file it finds in the source directory as an HTML file. The API documentation is used by the API filter to auto-generate links from the manual to the appropriate spot in the documentation. The particulars are covered a little later.

Configuration

You can configure various aspects of the manual by configuring it in the Hoe.spec block. The supported configuration attributes are:

manual_template_dir
Set the directory which contains the template directory for creating new manuals. This is the directory used by the manual task to create a manual from scratch, and also by the manual:update task to update the static resources.
manual_base_dir
Set the base directory of the manual build. All the paths other than manual_template_dir are relative to this directory unless they begin with '/'.
manual_source_dir
Set the directory which will contain the .page source files. Defaults to 'src'.
manual_layouts_dir
Set the directory which will contain the ERb layouts. Defaults to 'layouts'.
manual_output_dir
Set the directory which will contain the rendered manual output. Defaults to 'output'.
manual_resource_dir
Set the directory which will contain static resources that should be copied into the output directory. Defaults to 'resources'.
manual_lib_dir
Set the directory which will contain Ruby filter libraries. Defaults to 'lib'.
manual_metadata
An OpenStruct which can be used to inject metadata into page files. Plugins receive this as the third argument to their #process method, and it’s visible as a metadata local variable inside layouts and the default ERb filter.

Page Structure

Pages are structured as a file with a YAML header followed by a content section. The content is rendered via one or more plugins which are listed in the header, in the order they are specified.

Header

The page header, as mentioned before, is used to set metadata values that control page order in the index, the page’s title, which filters it will use to transform the page content, and other similar things.

title
Used in the HTML header, auto-generated indexes, and for referring to the page from other pages via the <?link ?> tag.
filters
The filters that should be used to render the page content, in the order they should be run.

Content

Filters

Built-in Filters

textile
Renders Textile markup as HTML. See Hoe::ManualGen::TextileFilter for details.
erb
Expands ERB tags. See Hoe::ManualGen::ErbFilter for details.

Default Filter Plugins

api
Generate links to API documentation. See Hoe::ManualGen::APIFilter for details.
editorial
Insert editorial markup. See Hoe::ManualGen::EditorialFilter for details.
examples
Insert example code with syntax highlighting, optional XMP filtering, and captioning. See Hoe::ManualGen::ExamplesFilter for details.
links
Insert automatically-generated links to other pages by page title or filename. See Hoe::ManualGen::LinksFilter for details.

Writing Your Own Filters

Filters should inherit from Hoe::ManualGen::PageFilter, and implement a public #process method. See Hoe::ManualGen::PageFilter for more details on how to write your own.

Customization

In addition to writing your own page filters, you can also customize your manual by replacing or adding ERB templates to the layouts directory. Each layout should contain:

<%= content %>
Minimum layout template.

The page’s content section will be filtered through all of its configured filters, and then set as the content local variable before the layout is rendered.

Authors

  • Michael Granger <ged@FaerieMUD.org>

License

Copyright © 2011, Michael Granger All rights reserved.

Redistribution and use 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 the authors nor contributors may be used to endorse or promote products derived from this software without specific prior written permission.

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.

Creative Commons License
The content of this manual, including images, video, and any example source code is licensed under a Creative Commons Attribution 3.0 License.