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?
  • URL of terminology server to use
  • identity of IG to generate for
    • --Lmckenzi (talk) 18:07, 12 May 2016 (EDT)What is this?
  • path to the version of the specification to generate from (the validation zip should be from this version with any local supplements)

once running and having loaded dependent definitions, it:

• --Lmckenzi (talk) 18:07, 12 May 2016 (EDT)loads all resources in the validation.zip
• reads the IG, and loads all the resources in the IG
• --Lmckenzi (talk) 18:07, 12 May 2016 (EDT)Resource or artifacts
• 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
• fhir.css - the css file to use for all the generated content
• header.fragment - what must be placed in header of the html files that use the generated fragments (.js and .css includes)
• the resources, after post-processing, ready for distribution
• a set of files, 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
• 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

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.

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