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 5 parameters:
  • the name of the validation.zip file to load
  • folders for dependent implementation guides
    • --Lmckenzi (talk) 18:07, 12 May 2016 (EDT) or an ini file listing them? GG: maybe - if they're required at all.
  • URL of terminology server to use
  • reference IG to generate
  • path to the version of the specification to generate from (the validation zip has to be from be from this version)

once running, it:

• loads all resources in the validation.zip
• 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 6th parameter, 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)

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

Special file

There's a special file, page-map.json, which has an array of "[id]-[type]" : "[filename]" which tells the IG publisher where to direct links in the generated content. This should be in the same folder as the implementation guide resource, and must be maintained by the editor.

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