Proposed new FHIR IG build Process

This is some notes about of the proposed new FHIR build process for publishing implementation guides

Summary

The publishing process is a 2 step process:

1. run the FHIR IG Publisher to validate all the resources & generate fragments
2. run a web site build tool to generate the final IG

FHIR IG Publisher

This is a java jar that can be run from the command line, or hosted in a process. Whether hosted in a process, or run from the command line, it works the following way:

• it takes 4 parameters:
  • the name of the control file to load (see below for documentation) (-ig)
  • URL of terminology server to use (-tx - defaults to http://fhir3.healthintersections.com.au)
  • path to the version of the specification to generate from (the validation zip has to be from be from this version) (-spec)
  • folder to output to (-out)

once running, it:

• loads all resources in the validation.zip
• reads the control file
• reads the IG, and loads all the resources in the IG
• processes code systems, value sets, structure definitions, structure maps
• validates the all resources in the IG
  • produce an HTML file with any errors encountered
• for each resource in the IG, generate a set of files - renderings of the artifact for possible inclusion in the published IG

On the command line, there is a 5th parameter (-reside), instructing the validator to stay loaded, and rerun the process anytime any of the source files are changed When run in process, the IG Publisher can be passed a resolver that is used to find content that is required when encountered (this is an alternative to specifying folders for the dependent implementation guides)

Control file

When the IG publisher is executed, it is pointed at a json file that contains publishing information about the Implementation Guide. Customarily, this is a json file in the same directory as the implementation guide resource, with the same [name].json. with this structure:

 {
   "source" : "payerextract.xml",
   "dependencies" [
   ]
   "paths" : [
   ]
 }

• source: the name of the implementation guide resource to publish
• dependencies: todo
• paths : todo (was: an array of "[id]-[type]" : "[filename]" which tells the IG publisher where to direct links in the generated content)

This file must be maintained by the editor of the implementation guide

Output

The output consists of a set of files in /output:

• validation.html - the result of validating the resources
• instructions.txt - how to use the generated fragments in the second part of the build (including what must be placed in header of the html files that use the generated fragments (.js and .css includes)

In /output/publish

• fhir.css - the css file to use for all the generated content (copy from spec)
• generated resources after post-processing, ready for distribution, in xml, json, turtle
• variables.json : an array of "name" : "value" pairs that provide useful information about fhir (e.g. version) so they can be built into the generated pages

In /output/fragments

• different generated views of the resources
  • each file has name [id]-[type].html where [id] is the id of the resource, and [type] is the type of generated html fragment. Todo: enumerate the types

in /output/pages

• a full html page, one for each generated fragment in /output/fragments
  • these are used for quality checking if there's problems with the fragments downstream

Output Fragments

These fragments are produced for each resource:

• [id]-html.xhtml - the narrative of the resource, as html
• [id]-gen-html.xhtml - the generated narrative of the resource, as html
• [id]-xml-html.xhtml - the xhtml rendering of the xml format of the resource, with hyperlinks
• [id]-json-html.xhtml - the xhtml rendering of the json format of the resource, with hyperlinks
• [id]-ttl-html.xhtml - the xhtml rendering of the turtle format of the resource, with hyperlinks

Build

The build program (todo: investigate and choose the appropriate tool) builds from a series of html or markdown pages, and may be integrated as part of a server (e.g. GitHub). The html source files and build tool injects the files that the IG publisher generated into the final output.

todo: fill out the details of this