1DBICx::AutoDoc(3) User Contributed Perl Documentation DBICx::AutoDoc(3)
2
6 DBICx::AutoDoc - Generate automatic documentation of
7 DBIx::Class::Schema objects
8
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 use DBICx:::AutoDoc;
14 my $ad = DBICx:::AutoDoc->new(
16 schema => 'MyApp::DB',
17 output => '/tmp',
18 );
19 $ad->fill_template( 'html' );
20
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
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 # pass options to constructor
34 my $ad = DBICx::AutoDoc->new( schema => 'MyApp::DB' );
35 # create object, then configure it
37 my $ad = DBICx::AutoDoc->new();
38 $ad->schema( 'MyApp::DB' );
39 schema( $schema );
41 Retrieve or set the class name of the DBIx::Class::Schema class you
42 want to document.
43 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 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 The default is not to attempt to connect, which gives you documentation
58 of the classes, rather than the database itself.
59 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 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 user( $username );
75 Get or set the username used to connect to the database. Ignored if
76 "connect" is false.
77 pass( $password );
79 Get or set the password used to connect to the database. Ignored if
80 "connect" is false.
81 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 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
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 package MyApp::DB::Schema;
99 use base qw( DBIx::Class::Schema );
100 our $VERSION = 42;
101 Then filename_base will return 'MyApp-DB-Schema-42'.
103 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 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 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 fill_templates( @templates );
122 This is simply a convenience method that calls fill_template for each
123 of the templates indicated.
124 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 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
137 These methods are generally used only internally, but are documented
138 for completeness.
139 byname
141 A sort routine for sorting an array of hashrefs by the 'name' key.
142 default_include_path
144 A class method that calculates and returns the default value for the
145 include_path.
146 find_template_file
148 Given the name of a template, returns the full path to the file
149 containing that template.
150 generated
152 Returns a timestamp that is used for the 'Generated at' line at the
153 bottom of the html output files.
154 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 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 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 get_unique_constraints_for( $source )
173 Given a source name, returns the unique constraints for that source (as
174 an array of hashrefs.)
175 get_vars
177 Assembles the output of all the data collection methods into a
178 structure suitable for passing to Template.
179 inheritance
181 Returns a structure indicating the inheritance heirarchy of the classes
182 used in the schema.
183 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 schema_class
190 Returns the name of the DBIx::Class::Schema subclass.
191 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 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 sources
202 Returns an arrayref of hashrefs containing information about each
203 source defined in the schema.
204
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 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 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 AUTODOC-dump.txt
229 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 AUTODOC-graph.dot, AUTODOC-graph.html, AUTODOC-graph.png
239 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 AUTODOC-inheritance.dot, AUTODOC-inheritance.html,
250 AUTODOC-inheritance.png
251 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 AUTODOC.html
257 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
263 These are the known bugs and/or limitations in the current version of
264 this package.
265 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 Having problems with GraphViz and fonts?
272 If you get an error from fdp that says something like:
273 Error: Could not find/open font : Times-Roman
275 Then you probably need to do the following:
277 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 Add a -Gfontpath option with the directory to the font
285 fdp -Gfontpath="/Library/Fonts" (other options from above)
286 Add fontname options for the Graph as well as for Nodes and Edges
288 -Gfontname=Arial -Nfontname=Arial -Efontname=Arial
289 So your final command line looks something like this:
291 fdp -Gfontpath=/Library/Fonts -Gfontname=Arial \
292 -Nfontname=Arial -Efontname=Arial
293 Then use this value as the c<--graphviz-command> option to dbicx-
295 autodoc, or as the "graphviz_command" option to DBICx::AutoDoc.
296 % dbicx-autodoc --schema=MyApp::DB --graphviz-command='fdp \
298 -Gfontpath=/Library/Fonts -Gfontname=Arial -Nfontname=Arial \
299 -Efontname=Arial' --output=./docs
300
302 dbicx-autodoc, DBICx::AutoDoc, DBIx::Class, DBIx::Class::Schema,
303 Template
304
306 Jason Kohles, <email@jasonkohles.com>
307
309 Copyright (C) 2007 by Jason Kohles
310 This library is free software; you can redistribute it and/or modify it
312 under the same terms as Perl itself.
313perl v5.32.1 2021-01-27 DBICx::AutoDoc(3)