path_handler.api

Summary	Creates Ruby API documentation pages via RDoc
Short name	api
Path patterns defined via /default.metainfo	/**/*.api
Provided by bundle	built-in
API doc	Webgen::PathHandler::Api

Description

This path handler automatically generates API documentation for Ruby projects using RDoc.

webgen is often used to create project websites for Ruby projects. Most of these projects also make the API documentation available online via RDoc. Using this path handler the API documentation can now have the same look and feel as the rest of the project website.

Usage

This path handler uses paths in Webgen Page Format to describe what API documentation should be generated. Note that content blocks are discarded and only the meta information block is used!

The only mandatory option is rdoc_options for specifying the RDoc options. When this path handler is invoked for an API path, it creates the necessary nodes and adds the needed tracking information so that changes in the RDoc source files are correctly detected.

Note that because of Ruby’s extensibility the whole API documentation needs to be regenerated when at least one RDoc source file changes.

Created Nodes

A page node (see path handler page) for each class/module is created and a fragment node for each constant, attribute and instance/class method.

The fragment nodes are created under appropriate parent fragment nodes, i.e. “Constants”, “Attributes”, “Class Methods” and “Instance Methods”. This allows one to easily display a table of contents using tag menu.

The nodes are created in a directory hierarchy reflecting the namespace hierarchy. This means that for a class Webgen::PathHandler::Api two directory nodes called Webgen/ and Webgen/PathHandler are created and a page node called Webgen/PathHandler/Api.html.

The  proxy_path meta information for the directory nodes is automatically set to the correct page node. Using the previous example this means that the proxy_path meta information for Webgen/PathHandler is automatically set to ../PathHandler.html.

The class/module documentation page nodes don’t contain any content. They are generated by a template that uses the :api_class_object node information (an instance of RDoc::ClassModule or one of its sub classes) set on the node to determine the class/module for which the HTML documentation should be created.

webgen provides a passive template node (at /templates/api.template) and an accompanying passive CSS node (at /stylesheets/api.css) based on the ‘darkfish’ RDoc template for generating the class/module documentation pages. A custom template can be specified via the api_template meta information (see below).

The CSS path is not automatically used by default. If it should be used by all API documentation nodes, one can use a meta information path and the  link meta information to link the CSS node to the API documentation nodes.

Special Meta Information Keys for API Nodes

rdoc_options (mandatory)

Either a string defining the RDoc options as passed to the rdoc command on the command line or an array of strings (i.e. the arguments array a program gets passed from the operating system).

Since the files of the Ruby project that should be documented are nearly always somewhere other than in the source directory of the website, the --root option needs to be used so that RDoc can correctly infer all paths.

dir_name (optional)

A string defining the name of the directory under which the API nodes should be placed. If this is not set, the basename of the path (without the extension) is automatically used.

api_name (optional)

A string defining a name for the API. If this is not set, the basename of the path (without the extension) is automatically used.

This value needs to be specified when multiple API paths are used so that webgen can distinguish between them.

prefix_link_defs (optional)

A boolean value which is used for deciding whether the API name (see the api_name key above) should be used as prefix for all link definitions.

The default value for this key, true, is set via the /default.metainfo path.

api_template (optional)

The alcn of the template that should be used to generate the class/module documentation.

The default for this key is /templates/api.template and set via the /default.metainfo path.

Automatically Defined Link Definitions

To simplify linking to classes, methods, attributes and constants, this path handler also automatically creates the necessary entries for the link_definitions extension.

The following link definition names are created:

• The full class/module name for classes and modules
• The full constant name for constants
• The full attribute name (including the class/module part) for attributes
• The full method name (including the class/module part) for instance and class methods

If the prefix_link_defs option is true, then the API name (defined via api_name) and a colon is used as prefix for all link definition names.

Example

Here is an example for the content of an api path /documentation/webgen.api:

---
rdoc_options: --root ../webgen/ ../webgen/lib
prefix_link_defs: false
dir_name: api
---

Note that there is no content block but only a meta information block with the special meta information keys that are needed.

If the special CSS path provided by webgen should be linked to the API documentation pages, the following needs to added to a meta information path:

--- alcn
/documentation/api/**/*.html:
  link:
    css: /stylesheets/api.css