Generate automatic documentation of DBIx::Class::Schema objects
Fetching latest commit…
Cannot retrieve the latest commit at this time
NAME DBICx::AutoDoc - Generate automatic documentation of DBIx::Class::Schema objects SYNOPSIS The recommended way to use this package is with the command-line tool dbicx-autodoc. You should check it's documentation for more details. use DBICx:::AutoDoc; my $ad = DBICx:::AutoDoc->new( schema => 'MyApp::DB', output => '/tmp', ); $ad->fill_template( 'html' ); DESCRIPTION DBICx::AutoDoc is a utility that can automatically generate documentation for your DBIx::Class schemas. It works by collecting information from several sources and arranging it into a format that makes it easier to deal with from templates. CONFIGURATION METHODS new( %configuration ) Create a new DBICx::AutoDoc object. Most of the methods below can also be passed to the constructor as configuration options. Which means that these two techniques are identical: # pass options to constructor my $ad = DBICx::AutoDoc->new( schema => 'MyApp::DB' ); # create object, then configure it my $ad = DBICx::AutoDoc->new(); $ad->schema( 'MyApp::DB' ); schema( $schema ); Retrieve or set the class name of the DBIx::Class::Schema class you want to document. output( $directory ); Retrieve or change the directory where the generated documentation will be placed. This directory will be created for you if it doesn't exist. The default is to put the output files in the current directory. connect( $true_or_false); The connect method allows you to specify whether an attempt will be made to connect to the actual database. If given a false value (the default) the documentation will be generated from only the code of your packages. If true, then "$schema-"connect> will be called before the documentation process begins (which means you may also have to set the "dsn", "user" and/or "pass" options.) The default is not to attempt to connect, which gives you documentation of the classes, rather than the database itself. Note that there are several parts of the documentation which may change, depending on whether you are connected or not, as some parts of your code may get modified by the database. As an example, when deploying to a PostgreSQL database, you might specify the data_type for your columns as 'varchar', but if you use the "connect" option, then the value reported by the database will probably be 'character varying' instead. dsn( $dsn ); Retrieve or change the DSN for the database. Might be included in the documenation (some templates display this value, some don't) but if "connect" is false, then it won't be used for anything other than displaying in the documentation. user( $username ); Get or set the username used to connect to the database. Ignored if "connect" is false. pass( $password ); Get or set the password used to connect to the database. Ignored if "connect" is false. include_path( $scalar_or_array_ref ); Get or set the value passed to Template's INCLUDE_PATH option. Unless you are making your own templates, you probably don't need to change this. The default is to look in the DBICx::AutoDoc 'auto' directory, which is where they get installed by Module::Install, and if not found there, to look in "$FindBin::Bin/templates", which allows you to use the dbicx-autodoc tool from an uninstalled copy of the package. METHODS filename_base Returns a base filename for the output files. By default this is based on the class name and version number of your schema. For example, if you schema looks like this: package MyApp::DB::Schema; use base qw( DBIx::Class::Schema ); our $VERSION = 42; Then filename_base will return 'MyApp-DB-Schema-42'. When a template is processed, the extension for the template is appended to the output from this method to determine the output filename. output_filename( $extension ); Given an extension, this method returns the filename that should be used for storing the output of the template associated with that extension. For example, using the previous example schema, if "output_filename( 'html' )" is called, it would return 'MyApp-DB-Schema-42.html'. When processing a template, this filename will be created in the directory specified by the "output" option. fill_template( $extension ); The "fill_template" method takes an argument of the file extension (which is also the template name) and renders that template into an appropriately named file in the output directory. fill_templates( @templates ); This is simply a convenience method that calls fill_template for each of the templates indicated. fill_all_templates Calling the "fill_all_templates" method is simply a convenience wrapper that calls "list_templates" to determine what templates are available, and then calls "fill_template" for each one in turn, thereby generating all the possible documentation for your schema. list_templates Returns a list of all the templates that are found in the "include_path". Names from this list can be passed to "fill_template" to genrate that documentation. INTERNAL METHODS These methods are generally used only internally, but are documented for completeness. byname A sort routine for sorting an array of hashrefs by the 'name' key. default_include_path A class method that calculates and returns the default value for the include_path. find_template_file Given the name of a template, returns the full path to the file containing that template. generated Returns a timestamp that is used for the 'Generated at' line at the bottom of the html output files. get_columns_for( $source ) Given a source name, returns the column information for the columns associated with that source (as an array of hashrefs.) get_relationships_for( $source ) Given a source name, returns the relationship information for the relations associated with that source (as an array of hashrefs.) get_simple_moniker_for( $source ) Given a source name, this method simply returns a simplified version of the name that has runs of non-word characters replaced with an underscore ("s/\W+/_/g") and has a number appended if two source names would otherwise reduce to the same (such as Foo-Bar and Foo::Bar.) The simplified moniker is used in some places where the non-word characters would otherwise cause problems (primarily in the GraphViz object names.) get_unique_constraints_for( $source ) Given a source name, returns the unique constraints for that source (as an array of hashrefs.) get_vars Assembles the output of all the data collection methods into a structure suitable for passing to Template. inheritance Returns a structure indicating the inheritance heirarchy of the classes used in the schema. relationship_map Assembles the output from the various relationship collecting methods into a format more useful for charting and graphing. Returns an arrayref of hashrefs. schema_class Returns the name of the DBIx::Class::Schema subclass. schema_version Returns the version of the DBIx::Class::Schema subclass. If the package doesn't define a version, it is assumed to be version 1. software_versions Returns a hashref of packages and their versions, mostly useful for debugging. Includes the versions of DBICx::AutoDoc, DBICx::AutoDoc::Magic, DBIx::Class, and Template. sources Returns an arrayref of hashrefs containing information about each source defined in the schema. TEMPLATES The templates used by this module are processed with the Template package. The template filename is the name the output file should have, with the word 'AUTODOC' in place of the generated name. Templates found in the "include_path" that start with 'AUTODOC' are assumed to be top-level templates, and can be passed to "fill_template" and will be included in the list returned by "list_templates". Templates that do not begin with 'AUTODOC' are assumed to be supporting templates that will be included by top-level templates. It is important to note that templates beginning with the two characters '#!' are treated differently than other templates. A normal template will be processed by Template directly into the appropriate output file. If the template begins with '#!' however, it will be processed into a script file, and then run. The script is expected to produce the appropriate output. See the AUTODOC-graph.png and AUTODOC-inheritance.png templates for examples of this. INCLUDED TEMPLATES Top-level templates included with the distribution are listed below. Examples of the output of the included templates can be found in the distribution's examples directory. AUTODOC-dump.txt This is a very simple template that just gets the generated data structure dumped using Data::Dump. The output is useful if you are creating your own templates, as you can use it to see what data has been collected from your schema, but if you are not creating templates then it isn't all that valuable. Note that there is not an example of this output in the distributions example directory, as it contains environmental information which may be sensitive. AUTODOC-graph.dot, AUTODOC-graph.html, AUTODOC-graph.png These templates are used to produce a GraphViz graph showing the relationships between the classes. The AUTODOC-graph.dot file produces a GraphViz .dot file that can be used by command-line utilities such as 'dot' or 'fdp' to produce various types of output. The AUTODOC-graph.png template runs fdp to produce a .png output file. The AUTODOC-graph.html template produces an HTML output file which includes a client-side image map, linking various parts of the diagram to the main html documentation. AUTODOC-inheritance.dot, AUTODOC-inheritance.html, AUTODOC-inheritance.png Similar to the AUTODOC-graph.* templates, these are used to generate GraphViz documentation of the inheritance heirarchy of the classes, rather than the relationships of the data. AUTODOC.html This is the main documentation template, that generates an html page which documents each classes source name, table name, column information, keys, unique constraints and relationships. KNOWN BUGS / LIMITATIONS These are the known bugs and/or limitations in the current version of this package. Not Windows compatible? There are probably some windows-incompatibilities in the code, I've tried to keep everything portable, but I'd be surprised if it works on Windows on the first try. Patches welcome. Having problems with GraphViz and fonts? If you get an error from fdp that says something like: Error: Could not find/open font : Times-Roman Then you probably need to do the following: Locate a truetype font on your system to use (or download one) [jason@critter ~ 0]$ locate .ttf ... /Library/Fonts/Arial.ttf ... Add a -Gfontpath option with the directory to the font fdp -Gfontpath="/Library/Fonts" (other options from above) Add fontname options for the Graph as well as for Nodes and Edges -Gfontname=Arial -Nfontname=Arial -Efontname=Arial So your final command line looks something like this: fdp -Gfontpath=/Library/Fonts -Gfontname=Arial \ -Nfontname=Arial -Efontname=Arial Then use this value as the c<--graphviz-command> option to dbicx-autodoc, or as the "graphviz_command" option to DBICx::AutoDoc. % dbicx-autodoc --schema=MyApp::DB --graphviz-command='fdp \ -Gfontpath=/Library/Fonts -Gfontname=Arial -Nfontname=Arial \ -Efontname=Arial' --output=./docs SEE ALSO dbicx-autodoc, DBICx::AutoDoc, DBIx::Class, DBIx::Class::Schema, Template AUTHOR Jason Kohles, <firstname.lastname@example.org> COPYRIGHT AND LICENSE Copyright (C) 2007 by Jason Kohles This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.