Tilda Command Line Utilities: Docs

<-- Command-Line Utilities

Docs

I wish we could have found an acronym that linked the 'D' in Tilda to 'Documentation'. Here is an official call to the community to help us fix that because Documentation is mandatory throughout Tilda model definitions and the same way Gen implements the 'Transparency' and Migrate implements the 'Iterative' parts of Tilda, Docs handles generating detailed documentation from models. It extracts HTML documentation and SQL scripts from an environment (via resources like JARs in the class path). The utility can take 1 or more parameters:

• A mandatory path to the folder where to put the documentation files from active Tilda schemas in the classpath.
• An optional path to a tilda.master.xxx.json file, or a list of schema names, to extract a subset of the documentation for specified schemas.

For example:

• Export docs and SQL for ALL the Tilda schemas found in the classpath
  • tilda.Docs C:\projects\docs\
• Export docs and SQL for the Tilda schemas listed in the master configuration file and their dependencies, grouped as defined, and found in the classpath.
  • tilda.Docs C:\projects\docs\ tilda.master.blah.json

The master configuration file is a JSON-based file:

 { "title": "Sample Database Master Index"
  ,"description":[
     "This database includes tables that represent operational and datamart capabilities of the main database."
    ]
  ,"groups":[
      { "name":"Group 1 Operational"
       ,"schemas":["Schema1", "Schema2"]
       ,"description":[
           "The Main 2 schemas, and automatically, their dependencies,"
          ,"for the first group"
         ]
      }
     ,{ "name":"Group 2 Datamarts"
       ,"schemas":["DMPatients", "DMFinancials", "DMClinicals"]
       ,"description":[
           "The datamart schemas and their related \"*Realized\" tables."
          ,"Blah blah blah"
         ]
      }
    ]
 }

The utility will export an HTML file TILDA___Docs.[schema_name].html and TILDA___[db_type].[schema_name].sql, and a master index file index.html. For example:

index.html
TILDA___Docs.SCHEMA1.html
TILDA___PostgreSQL.SCHEMA1.sql
TILDA___Docs.SCHEMA2.html
TILDA___PostgreSQL.SCHEMA2.sql
...