Disclaimer: This is a fork of jackscodemonkey's sphinx-sql, which aims to provide a tool to document database design within DDL source code.
It was extended by winkelband in Dec 2020 by the following features:
- Support more DDL objects (cluster objects like Role; catalog objects like Extension, Trigger, Materialized View [and other objects consist of two words]; objects with quoted names)
- Extract Table Attributes (Columns with metadata) (can be disabled); also Comments On Columns are parsed as the description (use one-line text, no markup!)
- Objects without a top-level comment are also listed
- Distinct header for tables generated by sphinx (Dependent Objects, ChangeLog, Attributes) by using the first row
- New examples in
tests/
to reflect the added features
- The following sections of this README were slighty modified:
- Installation
- Configuration
This fork utilizes a slightly modified version of ddlparse to parse table attributes (columns), but it also works with the original ddlparse (v1.9.0 tested).
Tip: If you create your DDL with pgModeler, you may want to look into this simple script to genrate single DDL files, which can be handled by sphinx-sql.
TODO:
See docs/source/todo.rst
sphinx-sql is a Sphinx documentation extension for building documentation from SQL source files.
* Have you had to troubleshoot a problem and someone has reorganized the documentation tree in Sharepoint?
* Has your company let PMs loose on projects with no idea how to version documentation, so now you have copies of entire doc trees in Sharepoint?
* Do you work on a database first development project?
* Do you look at auto documentation packages and cry siliently because no one cares about DB first development?
* Don't you wish you could maintain your project documentation with your code base, so you can check out and build the documents anytime you need them?
Having found nothing in the while that could help solve the db first problem, I've written sphinx-sql.
With a bit of standarization of comments in the top of the sql source files, we can maintain documentation that follows the code base.
This implimentation 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.
Install from PyPI:
pip install -e git://github.com/winkelband/sphinx-sql.git#egg=sphinx-sql
In your conf.py for Sphinx enable the extension:
extensions = [
'sphinx_sql.sphinx_sql',
]
By default, Table Columns with their metadata are extracted from the DDL. You can disable this behaviour by change settings in your conf.py:
sphinxsql_include_table_attributes = False
Create a new rst file (we'll call it autosql.rst) and include it in your toc-tree.
.. toctree::
:maxdepth: 2
:caption: Navigation:
autosql
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
It will extract the first block comment out of each file as well as important
object creatation lines such as CREATE TABLE / VIEW / FUNCTION / LANGUAGE etc.
Comments should adhear to the following formats, otherwise the regex searches will not find the appropriate blocks
Pipe delimiters are used in Parameters, Dependent Objects and Change Log files to create table rows in the documents, spaces don't matter; everything else is free form text and should appear as you write it.
Key word groups:
Return:
Purpose:
Dependent Objects:
ChangeLog:
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.
*/
TABLES/VIEWS/etc:
/*
Purpose:
This a new view to show how auto documentation can add new obejcts quickly.
Dependent Objects:
Type |Name
Table |schema1.ext_table
ChangeLog:
Date | Author | Ticket | Modification
2020-10-26 | Developer_2 | T-220 | Initial Definition
*/
DML:
can be included by providing key information in the top-level comment.
Object Name, Object Type are required fields in order to categorize and sort the output.
The remainder of the keywords are valid for use in DML blocks.
/*
Object Name: <schema.name>
Object Type: DML
Purpose:
This a new view to show how auto documentation can add new obejcts quickly.
ChangeLog:
Date | Author | Ticket | Modification
2020-10-26 | Developer_2 | T-220 | Initial Definition
*/