FHIR Chat · ig.ini · IG creation

Stream: IG creation

Topic: ig.ini

Josh Mandel (Jul 08 2020 at 16:48):

https://wiki.hl7.org/IG_Publisher_Documentation doesn't mention an ig.ini format. Can someone point to the right place for learning about this? In the auto builder, we always pass in ig.json to the publisher via -ig ig.json argument. @Jens Villadsen updated the auto-build README a few months back to say that ig.ini was also supported, but I haven't done any work to make that happen; is there some magic @Grahame Grieve in the publisher that would accept an arg like -ig ig.json even if no such file exists, and somehow default to a .ini instead of the supplied .json?

Jose Costa Teixeira (Jul 08 2020 at 17:07):

ig.ini is considerably trimmed now - it is documented inline
https://github.com/FHIR/sample-ig/blob/master/ig.ini

Jose Costa Teixeira (Jul 08 2020 at 17:18):

@Josh Mandel how would this be best documented? A link to the sample ig.ini in the wiki?

Jose Costa Teixeira (Jul 08 2020 at 17:19):

I would avoid duplicating documentation, hence the approach to document inline in the document itself

Jens Villadsen (Jul 08 2020 at 17:19):

Not just a sample, but also its content

Jose Costa Teixeira (Jul 08 2020 at 17:20):

the content is just (AFAIK) the implementation guide resource and the template.

Jens Villadsen (Jul 08 2020 at 17:20):

Which then should be documented

Jens Villadsen (Jul 08 2020 at 17:20):

IMHO

Jose Costa Teixeira (Jul 08 2020 at 17:21):

the code also indicates that there is an option to skip the terminology server, but the template handles that automatically.
(i think this is the code: https://github.com/HL7/fhir-ig-publisher/blob/2daaac0b48791d131924a0964394e43dd616ac9d/org.hl7.fhir.publisher.core/src/main/java/org/hl7/fhir/igtools/publisher/Publisher.java#L1510

Jose Costa Teixeira (Jul 08 2020 at 17:21):

Agree it should be well documented. Isn't this enough?

##########################
### ig.ini parameters: ###
##########################

#   ig: the name of the implementation guide resource file.
# examples:
# ig = input/myig.xml
# ig = input/implementationguide-example2.xml

#   template: the IG template that will be used to create the implementation guide (normally be a package name, but can be a local folder).
#   base fhir template:
#template = fhir.base.template

Jens Villadsen (Jul 08 2020 at 17:22):

Yep, if it is stated here as well https://confluence.hl7.org/plugins/servlet/mobile?contentId=35718627#content/view/35718627

Jose Costa Teixeira (Jul 08 2020 at 17:23):

yes, that is my point: I think the best is to point in the wiki to the file. This way we don't have to maintain documentation in 2 places

Jens Villadsen (Jul 08 2020 at 17:24):

That ought to do it, yes

Jens Villadsen (Jul 08 2020 at 17:33):

which makes me wonder ... why have that .ini file in the first place if its only two lines? if those parts fits into the json file, and the json files could be handled with the same sane defaults that are used when parsing the ini-file, it seems a bit gold plated to have two different formats for the same content

Jens Villadsen (Jul 08 2020 at 17:34):

@Lloyd McKenzie - what's your take on it?

Jose Costa Teixeira (Jul 08 2020 at 17:35):

json file is old fashion

Jens Villadsen (Jul 08 2020 at 17:36):

in what sense?

Jose Costa Teixeira (Jul 08 2020 at 17:40):

I meant it is the old way of doing things, because AFAIK it was deprecated some time ago - several of the attributes are now IG parameters, and the remaining ones are in the ig.ini.

Jens Villadsen (Jul 08 2020 at 17:41):

right ... ok ... so what about just having those as parameters to the ig publisher (the path to the IG resource and the template)?

Lloyd McKenzie (Jul 08 2020 at 17:42):

The name of the implementation guide varies. And depending on publishing framework, the location can vary too. The ini file provide a standard place for the CI build to look when it invokes the publisher

Jens Villadsen (Jul 08 2020 at 17:47):

isnt the name in the IG resource (or shouldn't it be)?

Jens Villadsen (Jul 08 2020 at 17:48):

my 2 cents are the following: whateever you can specify in the ig.ini should as well be possible to specify as command line parameter

Jose Costa Teixeira (Jul 08 2020 at 17:48):

the name of the file that contains the ig

Jens Villadsen (Jul 08 2020 at 17:49):

that should be a configurable parameter provided as command line parameter

Jean Duteau (Jul 08 2020 at 17:50):

Jens Villadsen said:

my 2 cents are the following: whateever you can specify in the ig.ini should as well be possible to specify as command line parameter

That might be an option, but for the CI builds, we don't know what the command line parameters are, so the ig.ini provides a spot where the publisher can look and get that info. it makes it easy for us to set up CI builds for all of the various guides.

Jose Costa Teixeira (Jul 08 2020 at 17:50):

Jens Villadsen said:

that should be a configurable parameter provided as command line parameter

or as a ini file so that people don't have to remember command line instruction

Jose Costa Teixeira (Jul 08 2020 at 17:52):

this way the command line is always the same for a given ig, and we avoid command line parameters

Jose Costa Teixeira (Jul 08 2020 at 17:54):

I was thinking this was a "nice to have" until I saw the impact it has : I have to run several IGs that I don't know much about, and I really don't want to look at file names, or remember command lines that may be different than the creator intended. I ust run the _genOnce which calls the ini. It saved me (and others) a good amount of time so far.

Jens Villadsen (Jul 08 2020 at 17:56):

I see - if I understand you correctly the ig.ini is basically a shorthand notation of the configuration of the CI / jenkins job that runs the CI pipeline

Jens Villadsen (Jul 08 2020 at 17:57):

that makes sense - now I'm just puzzled that it apparently hasn't been documented, and yet the pipeline works as intended using .ini files ;)

Josh Mandel (Jul 08 2020 at 19:09):

How does the pipeline work? Maybe @Grahame Grieve can shed light? In the auto-build pipeline I call the Publisher.jar with -ig ig.json (hard-coded into my invocation).

Grahame Grieve (Jul 08 2020 at 19:49):

there's special code for this circumstance, since you weren't responding to fix the ci-build when I needed it:

if (!f.exists() && mode == IGBuildMode.AUTOBUILD) {
      String s = Utilities.getDirectoryForFile(ig);
      f = new File(s == null ? System.getProperty("user.dir") : s);
    }

Grahame Grieve (Jul 08 2020 at 19:50):

ig.ini is supposed to contain precisely 2 values:

where to find the IG
which template to use - since this has to be loaded before reading the ig

And these should not and cannot be parameters on the command line since their value never varies

Grahame Grieve (Jul 08 2020 at 19:50):

Lloyd added a few more things but he promised to move them out

Josh Mandel (Jul 08 2020 at 20:57):

OK -- so is it fair to say we should document the .ini file with these two parameters at https://wiki.hl7.org/IG_Publisher_Documentation?

Re: auto-build, it's not clear whether/how I should update the code at this point. It seems like things are "working as expected"?

Josh Mandel (Jul 08 2020 at 20:58):

Does the logic you wrote above @Grahame Grieve support finding ig.ini only in the project root, or in other places too?

Josh Mandel (Jul 08 2020 at 20:58):

(I want to document this behavior in the README for the auto-builder.)

Grahame Grieve (Jul 08 2020 at 21:16):

the ig.ini must be in the root.

Grahame Grieve (Jul 08 2020 at 21:17):

it would be a good idea to update the documentation, sure. Thanks

Grahame Grieve (Jul 08 2020 at 21:17):

you don't need to make any fix to the code

Jose Costa Teixeira (Jul 08 2020 at 21:28):

Josh Mandel said:

OK -- so is it fair to say we should document the .ini file with these two parameters at https://wiki.hl7.org/IG_Publisher_Documentation?

I'll try to do it tomorrow - but on the new wiki https://confluence.hl7.org/display/FHIR/IG+Publisher+Documentation

Josh Mandel (Jul 08 2020 at 21:55):

Perfect! If content from https://wiki.hl7.org/IG_Publisher_Documentation has been fully migrated, I'd suggest deleting the content from that page and just including a link, because it's actually kind of hard to spot the "see Confluence instead" sentence at the top, and there's a ton of presumably-no-longer-maintained content below.