How can I generate documentation from comments in SQL DDL?

I have some SQL scripts that contain DDL to create tables and schemas for a database. I'd like to be able to comment this SQL and then use those comments to generate output documentation (in HTML). I want to be able to document the purpose of each table and table column, and have the output be nicely organized with a summary at the top and links to the specific tables (like the summary of methods on a class in Doxygen output). If it matters, the SQL is a member of the PostgreSQL family.

The specific purpose is to include schema documentation in published examples for a SQL platform -- so we want to, for example, describe a sample database and then use it to support examples of other queries, functions, etc. (I could imagine this also being used to give documentation to non-DBAs who are configuring BI tools on top of a database, but that is not my use case.)

The consumers of the documentation are not necessarily using this DDL (unless they run our scripts to set it up for themselves). We are currently documenting the tables by hand, which opens the door to the doc and DDL becoming out of sync in the future.

is a duplicate

This question has been asked before and has already been answered. It should be marked as a duplicate.

Please enter the URL of the proposed duplicate in the details field below.

not constructive

This question cannot be answered in a way that is helpful to anyone. It's not possible to learn something from possible answers, except for the solution for the specific problem of the asker.

Communities

How can I generate documentation from comments in SQL DDL?

1 comment thread

0 answers