Skip to main content

Sphinx extension for autodoc of SQL files.

Project description

Introduction

sphinx-sql is a Sphinx documentation extension for building documentation from SQL source files.

* Do you live in a bottomless pit of despair with “Living documents” in Sharepoint.
* 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 silently 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.

The goal of sphinx-sql is to provide an autodoc type module for database first development.
With a bit of standardization of comments in the top of the sql source files, we can maintain documentation that follows the code base.

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

sphinx-sql recursively looks for all .sql files under the configured sqlsource path.
It will extract the first block comment out of each file as well as important
object creation lines such as CREATE TABLE / VIEW / FUNCTION / LANGUAGE etc.

Comments should adhere 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:

Parameters:
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.
 */

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:

Files that are not a SQL object, but you’d like to include in documentation,
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 objects quickly.

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-sql-1.3.5.tar.gz (24.4 kB view details)

Uploaded Source

Built Distribution

sphinx_sql-1.3.5-py3-none-any.whl (21.6 kB view details)

Uploaded Python 3

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

Hashes for sphinx-sql-1.3.5.tar.gz
Algorithm Hash digest
SHA256 421136e86609a1fed8a87a14f709461cea6ea30cc542fd33ec7668ac63cf933d
MD5 efcaf7dfd8d741cb6aac7914f519e77b
BLAKE2b-256 6552eaa1e5f342acd027dd04e89dffbe823427c896a1995ee79d637e3821e611

See more details on using hashes here.

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

Hashes for sphinx_sql-1.3.5-py3-none-any.whl
Algorithm Hash digest
SHA256 c0e62f52a8d575d951670bdbbc18a0677f107f859b4755af274d36b106a9617c
MD5 15cd82c597caf24805d3811015b13a78
BLAKE2b-256 f253ded4b52e8e6860c58443ab1f57b9602875954a3170f6a32f8020a7e74c17

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page