|Summary||Creates Ruby API documentation pages via RDoc|
|Path patterns defined|
|Provided by bundle||built-in|
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.
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.
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
are created and a page node called
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
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
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
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
rdoccommand 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
--rootoption 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_namekey above) should be used as prefix for all link definitions.
The default value for this key,
true, is set via the
- 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.templateand set via the
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
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.
Here is an example for the content of an api path
--- 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