Configuring Sphinx

In your conf.py for Sphinx enable the extension:

extensions = [
'sphinx_sql.sphinx_sql',
]

Add the option to toggle including table attributes:

sphinxsql_include_table_attributes = True

By default, Table Columns with their metadata (data type, length, precision, scale) are extracted from the DDL. You can disable this behavior by changing sphinxsql_include_table_attributes = False in your conf.py.

Configure toctree

Create a new rst file (we’ll call it autosql.rst) and include it in your toc-tree.

.. toctree::
:maxdepth: 2
:caption: Navigation:

autosql

Configure rst

Add the directive with a relative path from your document build folder to the root of your SQL source in the autosql.rst file.

SQL Documentation
^^^^^^^^^^^^^^^^^

.. autosql::
    :sqlsource: ../../SQL

Add SQL Comments

Key word groups:

FUNCTIONS:

/*
 Parameters:
 Name | Type | Description

 Return: Void
 Purpose:
 Detailed explanation of the function which includes:
         - Function business logic
         - Transformation rules
         - Here is a bit more text.
 Dependent Objects:
     Type    |Name
     Table   |schema_name.source_table5
     View    |schema_name.target_table6
 ChangeLog:
     Date   |     Author      |    Ticket | Modification
         YYYY-MM-DD |        Developer name |        T-223 | Short Modification details or some really long text that will continue on.
 */

PROCEDURES:

/*
 Parameters:
 Name | Type | Description

 Purpose:
 Detailed explanation of the procedure which includes:
         - Procedure business logic
         - Transformation rules
         - Here is a bit more text.
 Dependent Objects:
     Type    |Name
     Table   |schema_name.source_table5
     View    |schema_name.target_table6
 ChangeLog:
     Date   |     Author      |    Ticket | Modification
         YYYY-MM-DD |        Developer name |        T-223 | Short Modification details or some really long text that will continue on.
 */

TABLES/VIEWS/etc:

You can comment on Table Columns (one-line text, no markups) in your DDL (COMMENT ON COLUMN). These comments will appear in the “Description” column inside the Attributes Block.

/*
Purpose:
This a new view to show how auto documentation can add new objects quickly.
Dependent Objects:
    Type    |Name
    Table   |schema1.ext_table
ChangeLog:
    Date    |    Author    |    Ticket    |    Modification
    2020-10-26    |  Developer_2  |   T-220    |    Initial Definition
*/

DML:

/*
Object Name: <schema.name>
Object Type: DML
Purpose:
This a new view to show how auto documentation can add new objects quickly.

ChangeLog:
    Date    |    Author    |    Ticket    |    Modification
    2020-10-26    |  Developer_2  |   T-220    |    Initial Definition
*/