...
This folder contains a few files of interest:
- publish-setup.ini json - contains information that is relevant for the IG publisher, so it knows how that publication is laid out and what web server is in use. This file is documented below.
- package-feed.xml - an RSS XML document that has an entry for each publication that has been made, so that robots/ fhir tools can easily find the publications. Note that this is an entry for each publication, not each IG. e.g. IGs are published repeatedly, and each time a new version is published, a new version specific reference to the IG is entered into this RSS feed. This RSS feed should be registered in https://github.com/FHIR/ig-registry/blob/master/package-feeds.json - make a PR registering it when the first IG is published
- publication-feed.xml - an equivalent to the package-feed.xml file, but intended for human consumption. e.g this would be registered in an RSS feed reader. The difference between this file and package-feed.xml is that this file contains references to index.html and package-feed.xml contains references to package.tgz.
...
The kind of things that the IG publisher does during this publication include (but are not limited to):
- create a new (version) lever folder
- copy in the specially built IG (it's a little different internally, because the IG publisher now knows exactly where it's going to live on the web, and what server will host it. none of the changes are visible to human readers of the specification)
- generate all the redirects as necessary
- update package-list.json, history.html, package-feed, publication-feed, organizational indexes
- if it's a milestone release:
- delete any content in the (ig) folder that isn't accounted for by the files that are expected to be found in there, and copy in another specially built copy of the IG
- touch every single previously published html file to update information about the current milestone version
To publish an IG, you need to have 5 folders:
- web-root - your local copy of the web-root folder as described above - this is an exact clone of the website. Keep a local back up copy for if things fail, since this is quicker to restore than copying again from the server. (note: a future version of this process may change how this works but for now, any publication requires a full copy of the server web folder)
- source - the source of the IG, ready to publish, with a prepared publication-request.json (see below).
- ig-history - a copy of the template for the history page. HL7 uses the github repo at https://github.com/HL7/fhir-ig-history-template
- ig-registry - a copy of the github repo at https://github.com/FHIR/ig-registry - this should be up to date, because the IG publisher will make changes in it that you then submit as a PR against the master (registers your IG at http://www.fhir.org/guides/registry/source - the source of the IG, ready to publish, with a prepared publication-request.json (see below).
- ig-history - a copy of the template for the history page. HL7 uses the github repo at https://github.com/HL7/fhir-ig-history-template
- ig-registry - a copy of the github repo at https://github.com/FHIR/ig-registry - this should be up to date, because the IG publisher will make changes in it that you then submit as a PR against the master (registers your IG at http://www.fhir.org/guides/registry/)
- templates - a copy of a local folder (usually a clone of a GitHub) repo that contains the web site specific templates (searchform.template, header.template, preamble.template, and postamble.template, and possibly an index.template)
- temp - which temp folder to use. defaults to the system temp which works fine except on OSX (some weird problem crops up on some OSX distros that we've never been able to pin down, so always specify a temp folder on an OSX device)
Prepared Publication Request
The source folder must contain a publication-request.json. This must contain a package-id and version that matches the version of the IG, that is fully populated per the documentation for publication-request.json.
Running the build
Invoking the publisher is simple, once you have all the content lined up:
java -jar publisher.jar -go-publish -source (source) -destination(web-root) -registry (ig-registry)/fhir-ig-list.json -history (ig-history) -temp (temp) -milestone
Notes:
- Only use -milestone if you're publishing a milestone (see discussion above)
- publisher.jar is the standard IG publisher jar. The parameter -go-publish invokes the special mode
- The first part of the publication process is an extensive set of checks that ensure the information submitted (especially including the package-list.json entries) is consistent with what has previously been published. You can run the publication process any number of times while getting all this stuff to line up.
- Once you see "All checks passed. Do the publication builds" in the output then you must re-sync web-root before re-running (it's not always safe to rerun, since some changes will accumulate) (you maintain a local copy to make this faster - e.g. hl7.org/fhir contains nearly 2 millon files in 10000+ directories, and it takes 1 or 2 days to resync)
- When the process is complete, you'll see "Finished Publishing". If you don't see that, something went wrong.
Documentation for publish.ini
The web-root folder contains publish.ini that tells the IG publisher about how the web-root folder is hosted:
...
In addition, of course, you need the web site where the source is going to be published to. There are two approaches
- Point the IG publisher directly at the web site. The IG publisher will download any files it needs from the website, and produce a folder of files that need to be copied up to the website
- Point the IG publisher at a local folder that contains all the files for the website. Typically, this is a GitHub repository that contains the web site source, but the IG Publisher is not concerned with the git(hub) part, it just works with the local folder
{web} is the address of either the web site (http(s)://...) or the local folder name.
Prepared Publication Request
The source folder must contain a publication-request.json. This must contain a package-id and version that matches the version of the IG, that is fully populated per the documentation for publication-request.json.
Running the build
Invoking the publisher is simple, once you have all the content lined up:
java -jar publisher.jar -go-publish -source (source) -web (web) -registry (ig-registry)/fhir-ig-list.json -history (ig-history) -templates (templates) -temp (temp)
Notes:
- publisher.jar is the standard IG publisher jar. The parameter -go-publish invokes the special mode
- The first part of the publication process is an extensive set of checks that ensure the information submitted (especially including the package-list.json entries) is consistent with what has previously been published. You can run the publication process any number of times while getting all this stuff to line up.
- The publisher currently pauses for a manual review of the content. Typically, you should open index.html in each of the folders for the IG in the nominated directory tree and check that it looks ok
- When the process is complete, you'll see "Finished Publishing". If you don't see that, something went wrong.
Documentation for publish-setup.json
The web-root folder contains publish.ini that tells the IG publisher about how the web-root folder is hosted:
{
"website" : {
"style" : "fhir.layout",
"url" : "http://fhir.org/guides",
"server" : "apache",
"org" : "FHIR Foundation",
"search-template" : "searchform.template.html",
"index-template" : "index.template"
},
"feeds" : {
"package" : "package-feed.xml",
"publication" : "publication-feed.xml"
}
}
Doco:
- style=fhir.layout - a fixed value that the IG publisher checks to make sure it's got the right file
- url= the web URL that this folder is found at
- server= the kind of server that hosts the web root. Values = iis, apache, nginx, lightspeed
- org = text description of the publishing org (appears in the rss feeds)
- feeds.package= where to put the package feed. This should not be changed
- feeds.publication= where to put the publication feed. This should not be changed
...