foliantcontrib.dbmldoc 0.3.4

Documentation generator for DBML specification format

DBML Docs Generator for Foliant

This preprocessor generates Markdown documentation from DBML specification files . It uses PyDBML for parsing DBML syntax and Jinja2 templating engine for generating Markdown.

Installation

$ pip install foliantcontrib.dbmldoc

Config

To enable the preprocessor, add dbmldoc to preprocessors section in the project config:

preprocessors:
    - dbmldoc

The preprocessor has a number of options:

preprocessors:
    - dbmldoc:
        spec_url: http://localhost/scheme.dbml
        spec_path: scheme.dbml
        doc: true
        scheme: true
        template: dbml.j2
        scheme_template: scheme.j2

spec_url : URL to DBML spec file. If it is a list — preprocessor uses the first url which works.

spec_path : Local path to DBML spec file (relative to project dir).

If both url and path params are specified — preprocessor first tries to fetch spec from url, and only if that fails looks for the file on the local path.

doc : If true — documentation will be generated. Set to false if you only want to draw a scheme of the database. Default true

scheme : If true — the platuml code for database scheme will be generated. Default true

template : Path to jinja-template for rendering the generated documentation. Path is relative to the project directory. If no template is specified preprocessor will use default template (and put it into project dir if it was missing). Default: dbml.j2

Note that the default template may be outdated. Please check if everything works, and if needed — update the template.

scheme_template : Path to jinja-template for generating planuml code for the database scheme. Path is relative to the project directory. If no template is specified preprocessor will use default template (and put it into project dir if it was missing). Default: scheme.j2

Usage

Add a <dbmldoc></dbmldoc> tag at the position in the document where the generated documentation should be inserted:

# Introduction

This document contains the automatically generated documentation of our Database schema.

<dbmldoc></dbmldoc>

Each time the preprocessor encounters the tag <dbmldoc></dbmldoc> it inserts the whole generated documentation text instead of it. The path or url to DBML spec file is taken from foliant.yml.

You can also override some parameters (or all of them) in the tag options:

# Introduction

Introduction text for API documentation.

<dbmldoc spec_url="http://localhost/schema.dbml"
         template="dbml.j2"
         scheme="false">
</dbmldoc>

# Database scheme

And here goes a visual diagram of our database:

<dbmldoc doc="false" scheme="true">
</dbmldoc>

Note that template path in tag is stated relative to the markdown file.

Tag parameters have the highest priority.

This way you can put your database description in one place and its diagram in the other (like in the example above). Or you can even have documentation from several different DBML spec files in one Foliant project.

Customizing output

The output markdown is generated by the Jinja2 template. Inside the template all data from the parsed DBML file is available under the data variable. It is in fact a PyDBMLParseResults object, as returned by PyDBML (see the docs to find out which attributes are available).

To customize the output create a template which suits your needs. Then supply the path to it in the template parameter. Same goes for the scheme template, which is defined in the scheme_template parameter.

If you wish to use the default template as a starting point, build the foliant project with dbmldoc preprocessor turned on. After the first build the default templates will appear in your foliant project dir under the names dbml.j2 and scheme.j2.