jackscodemonkey / sphinx-sql

Autodoc for PG SQL files
GNU General Public License v3.0
15 stars 5 forks source link

Support inline comments in create table statements #9

Open DaveGreasley opened 2 years ago

DaveGreasley commented 2 years ago

I use sphinx-sql for generating documentation of my HIVE tables. Currently sphinx-sql supports the "COMMENT ON COLUMN" format for column comments. However, HIVE SQL supports a friendlier format (see https://cwiki.apache.org/confluence/display/hive/languagemanual+ddl#LanguageManualDDL-CreateTable). Essentially you can do the following:

CREATE TABLE my_table (
    col1 STRING COMMENT 'this is a description of this column',
    col2 INTEGER COMMENT 'another useful comment'
)

Personally I much prefer this way of specifying comments as opposed to COMMENT ON COLUMN as it keeps the comment and column definition together.

I would like to add support for this style of comment, happy to raise a PR. The simplest option would be to add a new regex and add the code for finding the comments to the sphinx_sql module but as far as I can tell Postgres and other DB engines do not support this comment format. It could be better to create a new module that contained the code for HIVE specific DDL and add an option to the extension to enable it? @jackscodemonkey which would you prefer?

jackscodemonkey commented 2 years ago

@DaveGreasley I'd prefer the module with extension option to enable it. If the option was something generic that could be used for different databases to pull in their own module it would help keep different database formats containerized. If you'd like to raise the PR that would be great!