David E. Wheeler > Pod-Site-0.53 > Pod::Site

Download:
Pod-Site-0.53.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.53   Source  

Name ^

Pod::Site - Build browsable HTML documentation for your app

Synopsis ^

 use Pod::Site;
 Pod::Site->go;

Usage ^

  podsite --name App                      \
          --doc-root /path/to/output/html \
          --base-uri /browser/base/uri    \
          /path/to/perl/libs              \
          /path/to/perl/bins

Description ^

This program searches a list of directories and generates a jQuery-powered documentation site from all of the POD files it finds. It was originally designed for the Bricolage project but is has evolved for general use. Have a look at the Bricolage API Browser to see a sample documentation site in action. The generated documentation site supports Safari, Firefox, and IE7 and up.

Configuration

Sites generated by Pod::Site are static HTML sites with all interactivity powered by CSS and jQuery. It does its best to create links to documents within the site, and for Pod outside the site it links to CPAN search.

You can specify links directly to a specific document on your site by simply adding a module name to the URL after a question mark. An example:

  http://www.example.com/docs/?MooseX::Declare

There is one server configuration that you'll want to make to allow links without the question-mark:

  http://www.example.com/docs/MooseX::Declare

Getting this to work is simple: Just have your Web server send 404s to the index page. If your base URI is /docs/api, for example, in Apache's httpd.conf you can just do this:

 <Location /docs/api>
   ErrorDocument 404 /docs/current/api/index.html
 </Location>

Options ^

  -d --doc-root DIRECTORY   Browser document root
  -u --base-uri URI         Browser base URI
  -n --name NAME            Site name
  -t --versioned-title      Include main module version number in title
  -l --label LABEL          Label to append to site title
  -m --main-module MODULE   Primary module for the documentation
  -s --sample-module MODULE Module to use for sample links
  -i --index-file FILENAME  File name for index file
  -c --css-path PATH        Path to CSS file
  -j --js-path PATH         Path to CSS file
     --replace-css          Replace existing CSS file
     --replace-js           Replace existing JavaScript file
  -V --verbose              Incremental verbose mode.
  -h --help                 Print a usage statement and exit.
  -M --man                  Print the complete documentation and exit.
  -v --version              Print the version number and exit.

Class Interface ^

Class Method

go

  Pod::Site->go;

Called from podsite, this class method parses command-line options in @ARGV, passes them to the constructor, and builds the site.

Constructor

new

  my $ps = Pod::Site->new(\%params);

Constructs and returns a Pod::Site object. The supported parameters are:

module_roots

An array reference of directories to search for Pod files, or for the paths of Pod files themselves. These files and directories will be searched for the Pod documentation to build the browser.

doc_root

Path to a directory to use as the site document root. This directory will be created if it does not already exist.

base_uri

Base URI for the Pod site. For example, if your documentation will be served from /docs/2.0/api, then that would be the base URI for the site.

May be an array reference of base URIs. This is useful if your Pod site will be served from more than one URL. This is common for versioned documentation, where you might have docs in /docs/2.0/api and a symlink to that directory from /docs/current/api. This parameter is important to get links from one page to another within the site to work properly.

name

The name of the site. Defaults to the name of the main module.

versioned_title

If true, the version of the main module will be included in the site title.

label

Optional label to append to the site title. Something like "API Browser" is recommended.

main_module

The main module defining the site. For example, if you were building a documentation site for the Moose, Class::MOP, and MooseX namespaces, the main module would be "Moose". Defaults to the first module found when all module names are sorted in alphabetical order.

sample_module

Module to use in the example documentation links in the table of contents. This is the main page displayed on the site

index_file

Name of the site index file. Defaults to index.html, but you might need it to be, e.g., default.html if you were deploying to a Windows server.

css_path

Path to CSS files. Defaults to the base URI.

js_path

Path to JavaScript files. Defaults to the base URI.

replace_css
replace_js

If you're building a new site over an old site, by default Pod::Site will not replace the CSS and JavaScript files, seeing as you might have changed them. If you want it to replace them, pass a true value for this parameter.

If you're building a new site over an old site, by default Pod::Site will not replace the CSS and JavaScript files, seeing as you might have changed them. If you want it to replace them (and in general you ought to), pass a true value for these parameters.

verbose

Pass a value greater than 0 for verbose output. The higher the number, the more verbose (up to 3).

Instance Interface ^

Instance Methods

build

  $ps->build;

Builds the Pod::Site. This is likely the only instance method you'll ever need. In summary, it:

sort_files

 $ps->sort_files;

Iterates through the Pod files found by Pod::Simple::Search and sorts them into two categories: modules and scripts. All appear in the navigation tree, but scripts are listed under "bin" and are not otherwise in tree form.

start_nav

  $ps->start_nav($filehandle);

Starts the HTML for the navigation document, writing the output to $filehandle.

start_toc

  $ps->start_toc($filehandle);

Starts the HTML for the table of contents document, writing the output to $filehandle.

output

  $ps->output($filehandle, $tree);

Writes the content of the module tree to the navigation document via $filehandle. The $tree argument contains the tree. This method is called recursively as it descends through the tree to create the navigation tree.

output_bin

  $ps->output_bin($filehandle);

Outputs the list of script files to the table of contents document via $filehandle.

finish_nav

  $ps->finish_nav($filehandle);

Finishes the HTML for the navigation document, writing the output to $filehandle.

finish_toc

  $ps->finish_toc($filehandle);

Finishes the HTML for the table of contents document, writing the output to $filehandle.

batch_html

  $ps->batch_html;

Does the work of invoking Pod::Simple::HTMLBatch to look for Pod files and write out the corresponding HTML files for each.

copy_etc

  $ps->copy_etc;

Copies the additional files, podsite.js and podsite.css to the document root. These files are necessary to the functioning of the site.

get_desc

  $ps->get_desc( $module, $file);

Parses the Pod in $file to find the description of $module. This is the text after the hyphen in the `=head1 Name` section of the Pod, often called the "abstract" by toolchain modules like Module::Build.

Instance Accessors

main_module

  my $mod = $ps->main_module;

Returns the name of the main module as specified by the main_module parameter to new() or, if none was specified, as first module in the list of found modules, sorted case-insensitively.

sample_module

  my $mod = $ps->sample_module;

The name of the module to use for the sample links in the table of contents. Defaults to main_module.

name

  my $name = $ps->name;

Returns the name of the site. Defaults to main_module.

label

  my $label = $ps->label;

Returns the optional label to append to the site title. None by default.

title

  my $title = $ps->title;

Returns the title of the site. This will be constructed from name and label and, if versioned_title is true, the title of the main module.

nav_header

  my $header = $ps->nav_header;

Returns the header used at the top of the navigation. This will be constructed from name and, if versioned_title is true, the title of the main module.

versioned_title

  my $versioned_title = $ps->versioned_title;

Returns true if the version is to be included in the site title, and false if it is not, as specified via the versioned_title parameter to new().

version

  my $version = $ps->version;

Returns the version number of the main module.

module_roots

  my $roots = $ps->module_roots;

Returns an array reference of the directories and files passed to the module_roots parameter to new().

doc_root

  my $doc_root = $ps->doc_root;

Returns the path to the document root specified via the doc_root parameter to new().

base_uri

  my $base_uri = $ps->base_uri;

Returns the value of the base URI as specified via the base_uri parameter to new().

index_file

  my $index_file = $ps->index_file;

Returns the value of index files as specified via the index_file parameter to new(). Defaults to index.html.

css_path

  my $css_path = $ps->css_path;

Returns the URI path for CSS files as specified via the css_path parameter to new(). Defaults to an empty string, meaning it will be fetched from the directory relative to the current URL. This is the recommended value as it allows any URL under the base URL to work, such as /docs/MooseX::Declare, enabled by the Web server configuration.

js_path

  my $js_path = $ps->js_path;

Returns the URI path for JavaScript files as specified via the js_path parameter to new(). Defaults to an empty string, meaning it will be fetched from the directory relative to the current URL. This is the recommended value as it allows any URL under the base URL to work, such as /docs/MooseX::Declare, enabled by the Web server configuration.

replace_css

  my $replace_css = $ps->replace_css;

Returns true if Pod::Site should replace an existing podsite.css file when regenerating a site, as specified via the replace_css parameter to new().

replace_js

  my $replace_js = $ps->replace_js;

Returns true if Pod::Site should replace an existing podsite.js file when regenerating a site, as specified via the replace_js parameter to new().

mod_files

  my $mod_files = $ps->mod_files;

Returns a tree structure containing all the module files with Pod found by Pod::Simple::Search. The structure has file base names as keys and full file names as values. For nested structures, the keys are the last part of a module name and the values are an array of more file names and module branches. For example, a partial tree of module files for Moose might be structured like this:

  $mod_files = {
      'Moose.pm' => 'lib/Moose.pm',
      'Moose'    => {
          'Meta' => {
              'Class.pm'    => 'lib/Moose/Meta/Class.pm',
              'Instance.pm' => 'lib/Moose/Meta/Instance.pm',
              'Method.pm'   => 'lib/Moose/Meta/Method.pm',
              'Role.pm'     => 'lib/Moose/Meta/Role.pm',
          },
      },
 }

bin_files

  my $bin_files = $ps->bin_files;

Returns a tree structure containing all the scripts with Pod found by Pod::Simple::Search. The structure has file names as keys and full file names as values.

verbose

  my $verbose = $ps->verbose;

Returns the value passed for the verbose parameter to new(). Defaults to 0.

To Do ^

This module is stored in an open GitHub repository. Feel free to fork and contribute!

Found a bug? Please file a report!

Support ^

This module is stored in an open GitHub repository, http://github.com/theory/pod-site/. Feel free to fork and contribute!

Please file bug reports at http://github.com/theory/pod-site/issues/.

Author ^

David E. Wheeler <david@justatheory.com>

Copyright and License ^

Copyright (c) 2004-2010 David Wheeler. Some Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: