ILEDocs … the 3rd take … action!

ILEDocs is now in its third version and implementation. It started in RPG then transitioned to Java and now arrived in the Node.js world. It differentiates from its predecessor in that it now produces static HTML documents (again) instead of being a dynamic web application.

So what does it do and what has changed?

It still does what it should do: producing an API documentation of the programs and service programs, be it RPG or CL.

You still comment a program, module or procedure with a comment block like this:

1
2
3
4
5
6
7
8
///
// List order entries
//
// Returns all order entries for the specified order.
//
// @param Order number
// @return List of order entries, see order_entry_t
///

And the output is still HTML pages.

Though there are some new features added in this implementation.

New Features

  • No extra software required: Unlike the Java version, it doesn’t need any additional software — no database or application server. Just the program and the source code.
  • Cross-platform compatibility: It doesn’t have to run on IBM i, though it can, and doing so may have some advantages.
  • Multiple page generation: You can generate multiple HTML pages from a single source code base.
  • Optional overview page: If the content is split across multiple HTML pages, an overview page can optionally be generated.
  • JSON output: A JSON document containing the generated pages can be created for further programmatic processing.
  • Custom templates: The HTML templates can easily be replaced with your own custom set.

Requirements

As this is a Node.js application you need to install the Node.js runtime (version >= 14).

1
yum install nodejs20

Installation

The next step is to download the repository of the project into the IFS or clone the repository in the IFS.

To install the dependencies of this Node.js applications you need to execute

1
npm install

After having the dependencies installed the application can be built.

1
npm run build

Configuration

The configuration file defines what will be parsed and how/where the output will be generated. The format of the file is JSON.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "project": "project name",
  "title": "title used in templates",
  "output": {
    "path": "path to the output directory",
    "suffix": "suffix of the rendered pages, f. e. html"
  },
  "templates": { "path": "path to the templates directory" },
  "overview": ["index", "index_json"],
  "source": "path to the RPG or CL source code stream file",
  "section": []
}

Section

Each section can be configured as follows:

1
2
3
4
5
6
7
8
9
10
{
    "id" : "internal section id",
    "name" : "section name used in template",
    "startsWith" : "including symbols starting with this string (optional)",
    "symbols" : "symbols included by name (optional)",
    "default" : true | false,
    "order": pageOrder,
    "descriptionAsHeader" : true | false,
    "filename" : "page output filename"
}

If the project has defined a default section every symbol which cannot be mapped to a section will be mapped to the default section.

The order attribute defines the order/index in which the section is listed in the overview page.

Each page may have a block of text at the head of the page. If the text should be the ILEDocs description from the module then set descriptionAsHeader to true in the section config.

Start

The application can be started with npm start.

The project configuration file can be passed as a parameter to npm start:

1
npm start project-config-myapp.json

By default the output will be placed into the folder pages if not configured otherwise.

Debugging

The ILEDocs Page Builder project uses the debug package. To get the debugging output you just need to activate it by setting the environment variable DEBUG to iledocs:*.

1
export DEBUG=iledocs:*

or in Powershell

1
$env:DEBUG="iledocs:*"

To enable debugging output for single components see the list of defined logging namespaces for the application in the README of the project.

Example

The JSON and XML library noxDB is a great example. The prototypes, constants and data structures of this project are all placed in a single stream file. We split the content up into multiple pages.

  • Basics
  • Constants
  • Variables
  • Serializer
  • SQL
  • Generator and Parser

For each page the associated exported symbols which are going to go into that page are defined like this

1
2
3
4
5
{
  "id": "variables",
  "name": "Variables",
  "symbols": ["jx_DelimiterDS", "jx_iterator"]
}

or we can select all exported symbols which start with a given string:

1
2
3
4
5
6
{
  "id": "constants",
  "name": "Constants",
  "startsWith": "JX_",
  "order": 2
}

To add an overview page to the generation process we add the configuration entry overview as a top level attribute in the configuration JSON:

1
"overview" : ["index", "page"]

Note: You can see the full configuration file for noxDB at the ILEDocs Page Builder repository.

Limitations

Currently only a single stream file is parsed for generating the documentation. It would be nice to parse multiple stream files in the process.

Real World Example

All documentation available on iledocs.rpgnextgen.com has been generated by ILEDocs.

Wrap Up

It has never been easier to document programs and service programs and integrate the process into a build pipeline which also makes the publishing of the documentation very easy.

For any further information on ILEDocs Page Builder please take a look at README file in the project repository.

Happy documenting!

Mihael