Database Help Framework

Introduction to Database Help Framework

Database Help Framework allows editing database documentation in Microsoft Excel and generating the documentation in HTML format.

Also, it adds the hyperlinks to the online documentation into the Actions menu.

Using the framework gives the following benefits:

- Developers edit the documentation in Microsoft Excel, as plain text.
- The documentation is stored in a database.
- The edit forms and documentation include actual metadata about roles, schemas, objects, columns, and parameters.
- The documentation is integrated with the SaveToDB add-in.

You may use built-in SaveToDB Cell Editor (Options, Show Cell Editor) to edit the help:

The supplied help generation script supports the Markdown's formatting syntax for hyperlinks and images, H3 and H4 headers, bold and code tags.

This documentation is generated using this framework.

You may install, update, and remove Database Help Framework using SaveToDB Application Installer wizard.

You may generate a workbook to edit the help using the SaveToDB Application Workbooks wizard.

We are making a lot for developers.

We love to hear your feedback. Feel free to contact us.

Quick Start

1. Open Microsoft Excel, select the Database tab of the SaveToDB add-in.
2. Run Wizards, Application Installer.
3. Connect to your Microsoft SQL Server database and install Database Help Framework.
4. Run Wizards, Application Workbooks.
5. Generate the database_help.xlsx workbook.
6. Edit and save help for any object.
7. Click Actions, Generate Database Documentation.

Generating Documentation

You may get actual database help using the Actions menu.

To get the final documentation to publish online, use a batch file and a powershell script to get the final links and formatting.

Here is the batch file that we use to generate the planning application documentation:

@echo off
sqlcmd -S .\SQLExpress -E -d PlanningApp2 -y0 -Q "EXEC doc.xl_actions_database_documentation @language = 'en', @schema = 'x'" -f 65001 -o planning-application.htm
powershell.exe -file update-planning-application.ps1 planning-application.htm

To use this feature, run the PowerShell and set the execution policy to the Unrestricted:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

See more details about the Set-ExecutionPolicy cmdlet.

Here is a content of the update-planning-application.ps1 file:

if ($args.Length -eq 0)
{
   echo "Usage: update-planning-application.ps1 <filename>"
   exit
}
(Get-Content $args[0]  -encoding UTF8 -Raw) |
   Foreach-Object {$_ -replace ' (http[^ <]*\.htm)'                            , ' <a href="$1" class="external">$1</a>'} |
   Foreach-Object {$_ -replace '( |td>|<br>)((xls)\.[A-Za-z_1-9]+)'            , '$1<a href="#$2">$2</a>'} |
   Foreach-Object {$_ -replace '( |td>|<br>)((doc)\.[A-Za-z_1-9]+)'            , '$1<a href="#$2">$2</a>'} |
   Foreach-Object {$_ -replace '( |td>|<br>)((logs)\.[A-Za-z_1-9]+)'           , '$1<a href="#$2">$2</a>'} |
   Foreach-Object {$_ -replace '( |td>|<br>)((dbo25|xls25)\.[A-Za-z_1-9]+)'    , '$1<a href="#$2">$2</a>'} |
   Foreach-Object {$_ -replace ' (xls_users|xls_developers|xls_formats|xls_admins)'       , ' <a href="#role.$1">$1</a>'} |
   Foreach-Object {$_ -replace ' (doc_readers|doc_writers)'                    , ' <a href="#role.$1">$1</a>'} |
   Foreach-Object {$_ -replace ' (log_admins|log_users)'               , ' <a href="#role.$1">$1</a>'} |
   Foreach-Object {$_ -replace ' (planning_app_(admins|analysts|developers|users))', ' <a href="#role.$1">$1</a>'} |
   Foreach-Object {$_ -replace ' (xls) '                                       , ' <a href="#schema.$1">$1</a> '} |
   Foreach-Object {$_ -replace ' (doc) '                                       , ' <a href="#schema.$1">$1</a> '} |
   Foreach-Object {$_ -replace ' (logs) '                                      , ' <a href="#schema.$1">$1</a> '} |
   Foreach-Object {$_ -replace ' (dbo25|xls25) '                               , ' <a href="#schema.$1">$1</a> '} |
   Foreach-Object {$_ -replace '<p>#### *([^ \n]*)( *)([^ \n]*)( *)([^\n]*?)</p>' , '<h4 id="$1$3"><a name="$1$3"></a>$1$2$3$4$5</h4>'} |
   Foreach-Object {$_ -replace '<p>### *([^ \n]*)( *)([^ \n]*)( *)([^\n]*?)</p>'  , '<h3 id="$1$3"><a name="$1$3"></a>$1$2$3$4$5</h3>'} |
   Foreach-Object {$_ -replace '<p>```(\r\n)<br>'                              , '<p><code>$1'} |
   Foreach-Object {$_ -replace '<br>```(\r\n<br>)*</p>'                        , '</code></p>'} |
   Foreach-Object {$_ -replace '!\[(.*)\]\(([A-Za-z_\-1-9\\/:\.]*\.(png|jpg|gif))\)', '<img src="$2" title="$1" alt="$1" />'} |
   Foreach-Object {$_ -replace '\[([^\]\r\n]*)\]\((https://[^ \)\r\n]*)\)', '<a href="$2" class="external">$1</a>'} |
   Set-Content -Encoding UTF8 $args[0]

The script do the following:

- adds the external class to the http links;
- adds hyperlinks to database objects;
- adds hyperlinks to database roles;
- adds hyperlinks to database schemas;
- replaces ###Header to <h3>Header</h3>;
- replaces ####Header to <h4>Header</h4>;
- replaces ``` to <code> and </code>;
- replaces  to <img src=<url> title="title" alt="title" />;
- replaces [title](url) to hyperlinks.

You may add your rules yourself.
You have to replace the planning application names to yours.