[Dbix-class] Documentation of DBIx::Class schemas
Jason Kohles
email at jasonkohles.com
Wed Nov 14 21:15:46 GMT 2007
On Nov 14, 2007, at 7:05 AM, Pedro Melo wrote:
> On Nov 13, 2007, at 10:17 PM, Jason Kohles wrote:
>> On Nov 7, 2007, at 12:24 PM, Pedro Melo wrote:
>>> I was wondering how do you document your schemas?
>>>
>>> I started adding 'docs' keys to the extra hash for each column.
>>> I've also added a Doc component that allows me to set up some
>>> texts as documentation for the class.
>>>
>>> Then I can use basic introspection and generate the entire
>>> documentation (right now using a Catalyst::Controller).
>>>
>>> To prevent unnecessary memory usage in production, all the text of
>>> the docs is not kept unless a environment variable is set.
>> I'm actually doing the same thing, I've been working on a
>> DBIx::Class::AutoDoc package which includes a tool that takes a
>> DBIx::Class::Schema object and generates documentation for it,
>> similar to the documentation that is produced by postgresql_autodoc
>> (http://www.rbt.ca/autodoc/) but from the standpoint of documenting
>> the classes, rather than the database itself. I'm planning on an
>> initial release sometime this week, as soon as I can get a few last
>> issues worked out.
>
> This is my attempt at it. It works ok for me right now, no docs yet.
>
> http://scsys.co.uk:8001/10756
>
> To use, create a Cat controller and use base it like this:
>
> http://scsys.co.uk:8001/10757
>
> start at /docs/db and follow the links. I added the notion of table
> groups, it helps me sort tables into functional areas.
>
> A sample schema result class with documentation, PT, sorry :):
>
> http://scsys.co.uk:8001/10758
>
I was looking at it more from a utility standpoint, so mine doesn't
require Catalyst at all, it just generates documentation files...
Currently it's at the point where it will generate fairly complete
documentation in HTML, as well as diagrams (using GraphViz) of the
tables and the relationships...
There is a library you can use to generate documentation
programmatically (which is documented below), or there is also a
command-line tool which uses this library, making it extremely easy to
generate a whole bunch of documentation...
With the command line tool, it works something like this:
% dbix-class-autodoc --schema=MyApp::DB::Schema --output=/tmp/schema-
docs
% ls /tmp/schema-docs
MyApp-DB-Schema-1.html
MyApp-DB-Schema-1.dot
MyApp-DB-Schema-1.png
MyApp-DB-Schema-1.imap
And the documentation generation is all driven from Template::Toolkit,
which makes it very easy to change the look of the documentation if
you need to...
NAME
DBIx::Class::AutoDoc - Generate automatic documentation of
DBIx::Class::Schema objects
SYNOPSIS
use DBIx::Class::AutoDoc;
my $ad = DBIx::Class::AutoDoc->new(
schema => 'MyApp::DB',
output => '/tmp',
);
$ad->fill_template( 'html' );
DESCRIPTION
DBIx::Class::AutoDoc is an extension 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 DBIx::Class::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 = DBIx::Class::AutoDoc->new( schema => 'MyApp::DB' );
# create object, then configure it
my $ad = DBIx::Class::AutoDoc->new();
$ad->schema( 'MyApp::DB' );
schema( $schema );
Retrieve or set the class name of the DBIx::Class::Schema class
you want
to document. Note that you should let DBIx::Class::AutoDoc load
this
class for you, rather than "use"ing it yourself, especially if
you are
also using DBIx::Class::AutoDoc::Introspection (and if you are
using the
$DBIX_CLASS_AUTODOC trick documented in the
DBIx::Class::AutoDoc::Introspection documentation, it will only
work if
you let DBIx::Class::AutoDoc load your module, otherwise the
environment
variable won't get set for you.)
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 DBIx::Class::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
dbix-class-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.
TEMPLATES
The templates used by this module are processed with the Template
package. The template filename is the extension the output file
should
have, with a ".tt2" extension of it's own.
INCLUDED TEMPLATES
Templates included with the distribution are:
html
Generates an html page that documents each classes table name,
column
information, keys and relationships.
dot
Generates a .dot file which can be used by GraphViz to generate a
diagram of the relationships between the classes. In order to get a
graphic from the dot file, you need to run one of the graphing
commands
from the GraphViz package (I recommend 'fdp'), something like this:
fdp -Tpng -o MyApp-DB-Schema-42.png MyApp-DB-Schema-42.dot
dot_post
This template doesn't actually produce any output itself, instead
it
runs fdp for you to produce .png and .imap files from your .dot
source.
dump
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.
KNOWN BUGS / LIMITATIONS
These are the known bugs and/or limitations in the current
version of
this package.
Relationship data is difficult to determine.
Some aspects of DBIx::Class relationships are difficult (or
impossible)
to reverse-engineer from the relationship data available in the
classes
themselves. For example, many_to_many relationships cause
appropriate
methods to be generated in your classes, but they are not
registered
along with other relationships, so they will not appear in the
relationship documentation without some help.
You can alleviate this situation by using the helper component
included
with this distribution: DBIx::Class::AutoDoc::Introspection. This
component overloads the relationship creation methods, so that it
can
register the arguments the relationship was created with before
passing
control on to allow them to be created as normal.
Simple Moniker may be too simple
Some templates (like dot) need a simplified label that doesn't
contain
any non-word characters to uniquely identify an object. We create a
simple_moniker item for each source to fulfill this need, however
the
simple moniter is simply the regular moniker run through "s/\W+/_/
g", so
it's possible that two similarly named classes (i.e. Core::User and
Core-User) could simplify to the same moniker. You should either
make
sure you don't have any classes with this problem, or suggest a
better
solution than the one I have here (preferably with a patch to
implement
it.)
Having problems with GraphViz and fonts?
If you get an error from dot 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 at 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 -Tpng -Gfontpath="/Library/Fonts" -Gfontname=Arial \
-Nfontname=Arial -Efontname=Arial \
-o MyApp-DB-Schema-42.png MyApp-DB-Schema-42.dot
SEE ALSO
DBIx::Class, DBIx::Class::Schema, Template
AUTHOR
Jason Kohles, <email at jasonkohles.com>
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.
--
Jason Kohles, RHCA RHCDS RHCE
email at jasonkohles.com - http://www.jasonkohles.com/
"A witty saying proves nothing." -- Voltaire
More information about the DBIx-Class
mailing list