Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pod::Site(3)	      User Contributed Perl Documentation	  Pod::Site(3)

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
       <http://jquery.org/>-powered documentation site from all	of the POD
       files it	finds. It was originally designed for the Bricolage
       <http://bricolagecms.org/> project but is has evolved for general use.
       Have a look at the Bricolage API	Browser
       <http://www.bricolagecms.org/docs/current/api/> 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 <http://search.cpan.org/>.

       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
	    --favicon-uri URI	   Add a favicon linking to the	given URI
	 -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.

       "favicon_uri"
	   Link	to favicon file.  Extracts type	from extension.

       "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:

       o   Searches through the	module roots for Pod files (modules and
	   scripts) using Pod::Simple::Search

       o   Creates HTML	files for all the files	found using
	   Pod::Simple::HTMLBatch and a	custom subclass	of Pod::Simple::XHTML

       o   Iterates over the list of files to create the index with the
	   navigation tree and the table of contents page (toc.html).

       "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
       o   Add support for resizing the	nav pane.

       o   Allow right and middle clicks on nav	window links to	copy links or
	   open	them in	a new Window (Issue #1 <http://github.com/theory/pod-
	   site/issues/1>).

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

       Found a bug? Please file	a report <http://github.com/theory/pod-
       site/issues>!

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-2015 David E.	Wheeler. Some Rights Reserved.

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

perl v5.32.0			  2020-08-09			  Pod::Site(3)

Name | Synopsis | Usage | Description | Options | Class Interface | Instance Interface | To Do | Support | Author | Copyright and License

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Pod::Site&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help