Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Welcome to Software Development on Codidact!

Will you help us build our independent community of developers helping developers? We're small and trying to grow. We welcome questions about all aspects of software development, from design to code to QA and more. Got questions? Got answers? Got code you'd like someone to review? Please join us.

Post History

75%
+4 −0
Q&A 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)...

0 answers  ·  posted 4y ago by Monica Cellio‭  ·  edited 4y ago by Monica Cellio‭

#4: Post edited by user avatar Monica Cellio‭ · 2020-10-19T16:02:19Z (about 4 years ago)
responding to comments
  • What documentation-generation tools exist for SQL DDL?
  • 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) for users of the database. 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. The consumers of the documentation are not necessarily *using* this DDL (unless they run our scripts to set it up for themselves).
  • I'm thinking of something like Doxygen, but for SQL -- 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).
  • To what extent is this a solved problem? I'd like to use something that exists rather than writing it myself. If it matters, the SQL is a member of the PostgreSQL family.
  • 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.
  • How can I go about generating this kind of comment-driven documentation?
#3: Post edited by user avatar Monica Cellio‭ · 2020-10-19T12:49:36Z (about 4 years ago)
  • 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) for users of the database. (The specific purpose is to include schema documentation in published SQL examples.)
  • I'm thinking of something like Doxygen, but for SQL -- 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).
  • To what extent is this a solved problem? I'd like to use something that exists rather than writing it myself. If it matters, the SQL is a member of the PostgreSQL family.
  • 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) for users of the database. 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. The consumers of the documentation are not necessarily *using* this DDL (unless they run our scripts to set it up for themselves).
  • I'm thinking of something like Doxygen, but for SQL -- 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).
  • To what extent is this a solved problem? I'd like to use something that exists rather than writing it myself. If it matters, the SQL is a member of the PostgreSQL family.
#2: Post edited by user avatar Monica Cellio‭ · 2020-10-19T03:50:46Z (about 4 years ago)
  • What documentation-generation tools exist for SQL?
  • What documentation-generation tools exist for SQL DDL?
#1: Initial revision by user avatar Monica Cellio‭ · 2020-10-18T21:31:59Z (about 4 years ago)
What documentation-generation tools exist for SQL?
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) for users of the database.  (The specific purpose is to include schema documentation in published SQL examples.)

I'm thinking of something like Doxygen, but for SQL -- 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).

To what extent is this a solved problem?  I'd like to use something that exists rather than writing it myself.  If it matters, the SQL is a member of the PostgreSQL family.