[Dbix-class] Documentation of DBIx::Class schemas

[Ash Berlin]

Jason Kohles wrote:
> 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...
>
>
Do you do the graphing yourself? ro do you use SQL::Translator to do it 
for you?