Generating Model Documentation

The LLBLGen Pro designer offers the ability to generate extensive documentation of the whole project, all models and their connections as well as the meta-data. The documentation is generated as markdown in the DocNet format. DocNet, an open source static documentation site generator and the tool used to generate this documentation as well, can generate a static, searchable documentation site from the generated markdown files in a couple of seconds.

There are two example sites to see how the documentation sites look like: a Northwind based site and an Inheritance based site.

Setting up the code generation task

To generate documentation for the models in your project, add a custom code generation task for the source Project to the set of code generation tasks. To do so, please follow the following steps

  • Bring up the Code Generation Task Viewer, either by generating code (by pressing F7 or by selecting the menu Project -> Generate source code), or by selecting Project -> Configure Code Generation Tasks.
  • In the Code Generation Task Viewer, click the Add new code generation task for ... button and select Entire Project.
  • A new custom code generation task is added, with as source Project. You can configure it by double clicking it.
  • To generate model documentation for all models, the Platform has to be set to Documentation and the output language has to be set to Markdown. As preset SD.Project.Documentation has to be selected. By default these are all pre-selected. Specify the destination folder you want the markdown to be generated in. The preset will generate a subfolder Markdown in this folder.

Generating code will now generate the markdown files for your project in the specified output folder. This is also done when you have enabled automatic code generation and you save the project.

The markdown isn't automatically converted in a static site however, you have to run DocNet yourself. How to do that is described below.

Generating the site using DocNet

On the command line, navigate to the Markdown folder in the destination folder you've specified with the custom code generation task. You should see a list of folders, several markdown files and a docnet.json file, which defines the site's structure. To generate the static site from the markdown files, use DocNet on the command line using the following command: docnet -c .

This will call docnet (if you have docnet located in a path that's not in your path variable of your console, please specify the path in front of the docnet command) and specify the current folder as the source and that it should clear the destination folder first.

After a few seconds it has generated all html files in the Site folder in the destination folder you've specified with the custom code generation task. Open the index.htm file in a browser to view the site. It does contain the search information however most browsers don't allow searching with javascript of files read from disk. If you host the site using a webserver, the search will work ok, like it does in the example sites.

The site that's been generated has three main parts: the Entity Model, the Derived models (if any) and the Meta data. If an element depends on an element in another part, the site has links to these elements so you can navigate to these elements with ease and see what elements depend on which other elements.

It also offers an overview of what settings, attributes, interfaces and the like are defined on various elements, as well e.g. where which value types are used, which relationships are available and more. This can be of great help for developers who use the code generated from e.g. the entity model and don't have the designer to view the entity model to see how elements relate to each other.

If you use grouping in the entity model, these groups are also used to group elements in the documentation.