Autodoc - DocBook Output

Compiling HTML, PDF, or other formats out of a DocBook XML document is left as a task for the reader, but can be greatly helped by reading DocBook XSL: The Complete Guide and DocBook: The Definitive Guide.

PostgreSQL Autodoc outputs a book which is appropriate for compiling directory, or sectional inclusion into other DocBook documents as required. For richer database comments, try prefixing the comment with @DOCBOOK. This tells Autodoc that it is not to attempt escaping the data, but should include it as is, thus allowing several paragraphs of content, xinclude, xref, … to be included via the database objects comment block much like the below. However

Example 1. Possible comment

Note that Autodoc will wrap the comment in a para tag in the actual document. The below would have 2 paragraphs and 3 links to other content directly after the Public Schema title.

COMMENT ON SCHEMA public IS '@DOCBOOK
 This is the <literal>public</literal> schema which is better
 described by <xref linkend="link-to-public-schema">.
</para>
<para>
 For <application>Product</application> the <literal>public</literal>
 schema contains all the generic customer facing static literals such
 as <link linkend="public-table-status">status key codes</link> and 
 <link linkend="public-table-product">product key codes</link>.
';

Example 2. DocBook Example

Since this website is DocBook based, it was a simple matter of using an xinclude to include the appropriate content segment into this example. The below segment is based on the regression database and it's style could be greatly improved by playing with various DocBook XSL stylesheets.

autodocregress Model

Table of Contents

1. Schema inherit

Table: tab1
Table: tab1b
Table: taba
Table: tabb

2. Schema product

Table: product
worker( integer, integer )

3. Schema store

Table: inventory
Table: store

4. Schema warehouse

Table: inventory
View: products
Table: warehouse
worker( integer, integer )

List of Figures

4.1. Definition of view products

Chapter 1. Schema inherit

Table of Contents

Table: tab1
Table: tab1b
Table: taba
Table: tabb

Table: tab1

Structure of tab1

col1: integer

Table: tab1b

Structure of tab1b

col1: integer
cola: integer
colb: integer
col1b: integer

Table: taba

Structure of taba

cola: integer

Table: tabb

Structure of tabb

cola: integer
colb: integer

Chapter 2. Schema product

Table of Contents

Table: product
worker( integer, integer )

This schema stores a list of products and information about the product

Table: product

Structure of product

product_id: serial PRIMARY KEY
product_code: text UNIQUE NOT NULL
product_description: text

Constraints on product

product_product_code_check: CHECK ((product_code = upper(product_code)))

Tables referencing store.inventory via Foreign Key Constraints

store.inventory
warehouse.inventory

worker( integer, integer )

Function Properties

Language: SQL

Return Type: integer

Worker function appropriate for products

SELECT $1 + $1;

Chapter 3. Schema store

Table of Contents

Table: inventory
Table: store

Table: inventory

Store inventory

Structure of inventory

store_id: integer PRIMARY KEY REFERENCES store.store
product_id: integer PRIMARY KEY REFERENCES product.product
quantity: integer NOT NULL

Constraints on inventory

inventory_quantity_check: CHECK ((quantity > 0))

Table: store

Structure of store

store_id: serial PRIMARY KEY
store_code: text UNIQUE NOT NULL
store_description: text

Constraints on store

store_store_code_check: CHECK ((store_code = upper(store_code)))

Tables referencing store.inventory via Foreign Key Constraints

store.inventory

Chapter 4. Schema warehouse

Table of Contents

Table: inventory
View: products
Table: warehouse
worker( integer, integer )

A list of warehouses and information on warehouses

Table: inventory

Warehouse inventory

Structure of inventory

warehouse_id: integer PRIMARY KEY REFERENCES warehouse.warehouse
product_id: integer PRIMARY KEY REFERENCES product.product
quantity: integer NOT NULL

Constraints on inventory

inventory_quantity_check: CHECK ((quantity > 0))

Indexes on inventory

quantity_index: quantity

View: products

Structure of products

product_id: integer
product_code: text
product_description: text

Figure 4.1. Definition of view products

SELECT DISTINCT product.product_id
, product.product_code
, product.product_description 
FROM (warehouse.inventory 
  JOIN product.product 
 USING (product_id)
)
ORDER BY product.product_id
, product.product_code
, product.product_description;

Table: warehouse

Structure of warehouse

warehouse_id

serial PRIMARY KEY

warehouse_code

text UNIQUE NOT NULL

Internal code which represents warehouses for invoice purposes

warehouse_manager

text NOT NULL

Name of Warehouse Manager

warehouse_supervisor

text UNIQUE

Supervisors name for a warehouse when one has been assigned. The same supervisor may not be assigned to more than one warehouse, per company policy XYZ.

warehouse_description

text

Constraints on warehouse

warehouse_check: CHECK ((upper(warehouse_manager) <> upper(warehouse_supervisor)))
warehouse_warehouse_code_check: CHECK ((warehouse_code = upper(warehouse_code)))

Tables referencing warehouse.inventory via Foreign Key Constraints