Sphinx extension for autodoc of SQL files.
Project description
Introduction
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.
Installation
Install from PyPI:
pip install sphinx-sql
Configuration
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
*/
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file sphinx-sql-1.3.5.tar.gz
.
File metadata
- Download URL: sphinx-sql-1.3.5.tar.gz
- Upload date:
- Size: 24.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.17
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 421136e86609a1fed8a87a14f709461cea6ea30cc542fd33ec7668ac63cf933d |
|
MD5 | efcaf7dfd8d741cb6aac7914f519e77b |
|
BLAKE2b-256 | 6552eaa1e5f342acd027dd04e89dffbe823427c896a1995ee79d637e3821e611 |
File details
Details for the file sphinx_sql-1.3.5-py3-none-any.whl
.
File metadata
- Download URL: sphinx_sql-1.3.5-py3-none-any.whl
- Upload date:
- Size: 21.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.17
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | c0e62f52a8d575d951670bdbbc18a0677f107f859b4755af274d36b106a9617c |
|
MD5 | 15cd82c597caf24805d3811015b13a78 |
|
BLAKE2b-256 | f253ded4b52e8e6860c58443ab1f57b9602875954a3170f6a32f8020a7e74c17 |