1DBICx::AutoDoc(3)     User Contributed Perl Documentation    DBICx::AutoDoc(3)
2
3
4

NAME

6       DBICx::AutoDoc - Generate automatic documentation of
7       DBIx::Class::Schema objects
8

SYNOPSIS

10       The recommended way to use this package is with the command-line tool
11       dbicx-autodoc.  You should check it's documentation for more details.
12
13         use DBICx:::AutoDoc;
14
15         my $ad = DBICx:::AutoDoc->new(
16           schema  => 'MyApp::DB',
17           output  => '/tmp',
18         );
19         $ad->fill_template( 'html' );
20

DESCRIPTION

22       DBICx::AutoDoc is a utility that can automatically generate
23       documentation for your DBIx::Class schemas.  It works by collecting
24       information from several sources and arranging it into a format that
25       makes it easier to deal with from templates.
26

CONFIGURATION METHODS

28   new( %configuration )
29       Create a new DBICx::AutoDoc object.  Most of the methods below can also
30       be passed to the constructor as configuration options.  Which means
31       that these two techniques are identical:
32
33         # pass options to constructor
34         my $ad = DBICx::AutoDoc->new( schema => 'MyApp::DB' );
35
36         # create object, then configure it
37         my $ad = DBICx::AutoDoc->new();
38         $ad->schema( 'MyApp::DB' );
39
40   schema( $schema );
41       Retrieve or set the class name of the DBIx::Class::Schema class you
42       want to document.
43
44   output( $directory );
45       Retrieve or change the directory where the generated documentation will
46       be placed.  This directory will be created for you if it doesn't exist.
47       The default is to put the output files in the current directory.
48
49   connect( $true_or_false);
50       The connect method allows you to specify whether an attempt will be
51       made to connect to the actual database.  If given a false value (the
52       default) the documentation will be generated from only the code of your
53       packages.  If true, then "$schema-"connect> will be called before the
54       documentation process begins (which means you may also have to set the
55       "dsn", "user" and/or "pass" options.)
56
57       The default is not to attempt to connect, which gives you documentation
58       of the classes, rather than the database itself.
59
60       Note that there are several parts of the documentation which may
61       change, depending on whether you are connected or not, as some parts of
62       your code may get modified by the database.  As an example, when
63       deploying to a PostgreSQL database, you might specify the data_type for
64       your columns as 'varchar', but if you use the "connect" option, then
65       the value reported by the database will probably be 'character varying'
66       instead.
67
68   dsn( $dsn );
69       Retrieve or change the DSN for the database.  Might be included in the
70       documenation (some templates display this value, some don't) but if
71       "connect" is false, then it won't be used for anything other than
72       displaying in the documentation.
73
74   user( $username );
75       Get or set the username used to connect to the database.  Ignored if
76       "connect" is false.
77
78   pass( $password );
79       Get or set the password used to connect to the database.  Ignored if
80       "connect" is false.
81
82   include_path( $scalar_or_array_ref );
83       Get or set the value passed to Template's INCLUDE_PATH option.  Unless
84       you are making your own templates, you probably don't need to change
85       this.
86
87       The default is to look in the DBICx::AutoDoc 'auto' directory, which is
88       where they get installed by Module::Install, and if not found there, to
89       look in "$FindBin::Bin/templates", which allows you to use the dbicx-
90       autodoc tool from an uninstalled copy of the package.
91

METHODS

93   filename_base
94       Returns a base filename for the output files.  By default this is based
95       on the class name and version number of your schema.  For example, if
96       you schema looks like this:
97
98         package MyApp::DB::Schema;
99         use base qw( DBIx::Class::Schema );
100         our $VERSION = 42;
101
102       Then filename_base will return 'MyApp-DB-Schema-42'.
103
104       When a template is processed, the extension for the template is
105       appended to the output from this method to determine the output
106       filename.
107
108   output_filename( $extension );
109       Given an extension, this method returns the filename that should be
110       used for storing the output of the template associated with that
111       extension.  For example, using the previous example schema, if
112       "output_filename( 'html' )" is called, it would return
113       'MyApp-DB-Schema-42.html'.  When processing a template, this filename
114       will be created in the directory specified by the "output" option.
115
116   fill_template( $extension );
117       The "fill_template" method takes an argument of the file extension
118       (which is also the template name) and renders that template into an
119       appropriately named file in the output directory.
120
121   fill_templates( @templates );
122       This is simply a convenience method that calls fill_template for each
123       of the templates indicated.
124
125   fill_all_templates
126       Calling the "fill_all_templates" method is simply a convenience wrapper
127       that calls "list_templates" to determine what templates are available,
128       and then calls "fill_template" for each one in turn, thereby generating
129       all the possible documentation for your schema.
130
131   list_templates
132       Returns a list of all the templates that are found in the
133       "include_path".  Names from this list can be passed to "fill_template"
134       to genrate that documentation.
135

INTERNAL METHODS

137       These methods are generally used only internally, but are documented
138       for completeness.
139
140   byname
141       A sort routine for sorting an array of hashrefs by the 'name' key.
142
143   default_include_path
144       A class method that calculates and returns the default value for the
145       include_path.
146
147   find_template_file
148       Given the name of a template, returns the full path to the file
149       containing that template.
150
151   generated
152       Returns a timestamp that is used for the 'Generated at' line at the
153       bottom of the html output files.
154
155   get_columns_for( $source )
156       Given a source name, returns the column information for the columns
157       associated with that source (as an array of hashrefs.)
158
159   get_relationships_for( $source )
160       Given a source name, returns the relationship information for the
161       relations associated with that source (as an array of hashrefs.)
162
163   get_simple_moniker_for( $source )
164       Given a source name, this method simply returns a simplified version of
165       the name that has runs of non-word characters replaced with an
166       underscore ("s/\W+/_/g") and has a number appended if two source names
167       would otherwise reduce to the same (such as Foo-Bar and Foo::Bar.)  The
168       simplified moniker is used in some places where the non-word characters
169       would otherwise cause problems (primarily in the GraphViz object
170       names.)
171
172   get_unique_constraints_for( $source )
173       Given a source name, returns the unique constraints for that source (as
174       an array of hashrefs.)
175
176   get_vars
177       Assembles the output of all the data collection methods into a
178       structure suitable for passing to Template.
179
180   inheritance
181       Returns a structure indicating the inheritance heirarchy of the classes
182       used in the schema.
183
184   relationship_map
185       Assembles the output from the various relationship collecting methods
186       into a format more useful for charting and graphing.  Returns an
187       arrayref of hashrefs.
188
189   schema_class
190       Returns the name of the DBIx::Class::Schema subclass.
191
192   schema_version
193       Returns the version of the DBIx::Class::Schema subclass.  If the
194       package doesn't define a version, it is assumed to be version 1.
195
196   software_versions
197       Returns a hashref of packages and their versions, mostly useful for
198       debugging.  Includes the versions of DBICx::AutoDoc,
199       DBICx::AutoDoc::Magic, DBIx::Class, and Template.
200
201   sources
202       Returns an arrayref of hashrefs containing information about each
203       source defined in the schema.
204

TEMPLATES

206       The templates used by this module are processed with the Template
207       package.  The template filename is the name the output file should
208       have, with the word 'AUTODOC' in place of the generated name.
209       Templates found in the "include_path" that start with 'AUTODOC' are
210       assumed to be top-level templates, and can be passed to "fill_template"
211       and will be included in the list returned by "list_templates".
212       Templates that do not begin with 'AUTODOC' are assumed to be supporting
213       templates that will be included by top-level templates.
214
215       It is important to note that templates beginning with the two
216       characters '#!'  are treated differently than other templates.  A
217       normal template will be processed by Template directly into the
218       appropriate output file.  If the template begins with '#!' however, it
219       will be processed into a script file, and then run.  The script is
220       expected to produce the appropriate output.  See the AUTODOC-graph.png
221       and AUTODOC-inheritance.png templates for examples of this.
222
223   INCLUDED TEMPLATES
224       Top-level templates included with the distribution are listed below.
225       Examples of the output of the included templates can be found in the
226       distribution's examples directory.
227
228       AUTODOC-dump.txt
229
230       This is a very simple template that just gets the generated data
231       structure dumped using Data::Dump.  The output is useful if you are
232       creating your own templates, as you can use it to see what data has
233       been collected from your schema, but if you are not creating templates
234       then it isn't all that valuable.  Note that there is not an example of
235       this output in the distributions example directory, as it contains
236       environmental information which may be sensitive.
237
238       AUTODOC-graph.dot, AUTODOC-graph.html, AUTODOC-graph.png
239
240       These templates are used to produce a GraphViz graph showing the
241       relationships between the classes.  The AUTODOC-graph.dot file produces
242       a GraphViz .dot file that can be used by command-line utilities such as
243       'dot' or 'fdp' to produce various types of output.  The
244       AUTODOC-graph.png template runs fdp to produce a .png output file.  The
245       AUTODOC-graph.html template produces an HTML output file which includes
246       a client-side image map, linking various parts of the diagram to the
247       main html documentation.
248
249       AUTODOC-inheritance.dot, AUTODOC-inheritance.html,
250       AUTODOC-inheritance.png
251
252       Similar to the AUTODOC-graph.* templates, these are used to generate
253       GraphViz documentation of the inheritance heirarchy of the classes,
254       rather than the relationships of the data.
255
256       AUTODOC.html
257
258       This is the main documentation template, that generates an html page
259       which documents each classes source name, table name, column
260       information, keys, unique constraints  and relationships.
261

KNOWN BUGS / LIMITATIONS

263       These are the known bugs and/or limitations in the current version of
264       this package.
265
266   Not Windows compatible?
267       There are probably some windows-incompatibilities in the code, I've
268       tried to keep everything portable, but I'd be surprised if it works on
269       Windows on the first try.  Patches welcome.
270
271   Having problems with GraphViz and fonts?
272       If you get an error from fdp that says something like:
273
274         Error: Could not find/open font : Times-Roman
275
276       Then you probably need to do the following:
277
278       Locate a truetype font on your system to use (or download one)
279             [jason@critter ~ 0]$ locate .ttf
280             ...
281             /Library/Fonts/Arial.ttf
282             ...
283
284       Add a -Gfontpath option with the directory to the font
285             fdp -Gfontpath="/Library/Fonts" (other options from above)
286
287       Add fontname options for the Graph as well as for Nodes and Edges
288             -Gfontname=Arial -Nfontname=Arial -Efontname=Arial
289
290       So your final command line looks something like this:
291             fdp -Gfontpath=/Library/Fonts -Gfontname=Arial \
292               -Nfontname=Arial -Efontname=Arial
293
294           Then use this value as the c<--graphviz-command> option to dbicx-
295           autodoc, or as the "graphviz_command" option to DBICx::AutoDoc.
296
297             % dbicx-autodoc --schema=MyApp::DB --graphviz-command='fdp \
298               -Gfontpath=/Library/Fonts -Gfontname=Arial -Nfontname=Arial \
299               -Efontname=Arial' --output=./docs
300

SEE ALSO

302       dbicx-autodoc, DBICx::AutoDoc, DBIx::Class, DBIx::Class::Schema,
303       Template
304

AUTHOR

306       Jason Kohles, <email@jasonkohles.com>
307
309       Copyright (C) 2007 by Jason Kohles
310
311       This library is free software; you can redistribute it and/or modify it
312       under the same terms as Perl itself.
313
314
315
316perl v5.32.1                      2021-01-27                 DBICx::AutoDoc(3)
Impressum