sphinx-sql is a Sphinx documentation extension for building documentation from SQL source files.
Having found nothing in the while that could help solve the db first problem, I've written sphinx-sql.
This implementation is tested against Greenplum / Postgres, those are the databases I work with on a daily basis. If you want to extend functionality, have a quick look at the contrib section of this document.
Tip: If you create your DDL with pgModeler, you may want to look into this simple script to conveniently generate single DDL files, which can be handled by sphinx-sql.
Install from PyPI:
pip install sphinx-sqlIn 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 = TrueBy 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.
Create a new rst file (we'll call it autosql.rst) and include it in your toc-tree.
.. toctree::
:maxdepth: 2
:caption: Navigation:
autosqlAdd 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: ../../SQLKey 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
*/