Stream: genomics/committers
Topic: Convert to new template
Kevin Power (Aug 04 2020 at 22:11):
@Lloyd McKenzie posted the following on #committers/announce :
Lloyd McKenzie
On our call last week, the FMG approved a policy requiring that FHIR implementation guides going to ballot in the January 2020 cycle or being published after the start of the January cycle SHALL use either the HL7 FHIR standard template or one otherwise approved by the FMG (e.g. the Da Vinci template). Any exception requires FMG approval - which should be sought well in advance. If you have any questions, please raise them on the #committers or #IG creation stream.
What to see if anyone has looked into what it would take for us to switch over to the new template? @Lloyd McKenzie any thoughts?
Lloyd McKenzie (Aug 04 2020 at 23:50):
Won't be hard. A couple hours effort, mainly moving files to the appropriately named folder. You can look at http://github.com/fhir/sample-ig to see the layout.
Kevin Power (Aug 05 2020 at 00:49):
I will take a look , thanks
Kevin Power (Aug 05 2020 at 20:42):
OK, played around with this some last night and tweaked a few more things today, and we now have a branch with the new template implemented:
http://build.fhir.org/ig/HL7/genomics-reporting/branches/switch_structdefs/index.html
Feedback welcome.
Kevin Power (Aug 05 2020 at 20:44):
And yes, this is the same branch I used to switch over to StructureDefinitions.
Jamie Jones (Aug 05 2020 at 21:07):
I'm not a huge fan of the fade-in-from-white on every page load but it looks great in the template! Glad the appendices still work
Kevin Power (Aug 05 2020 at 21:10):
Jamie Jones said:
I'm not a huge fan of the fade-in-from-white on every page load
I concur. I thought I was passing out when I first saw it.
Glad the appendices still work
The extra stuff in the menu took some tweaking for sure, but I think it is worth it.
Kevin Power (Aug 05 2020 at 21:39):
One change that I should point out to everyone. Before this change, our profile pages were accessible like this:
http://build.fhir.org/ig/HL7/genomics-reporting/variant.html - note the variant.html
It seems the new template changes something about the build process such that the pages are now prefixed with StructureDefinition- like this:
http://build.fhir.org/ig/HL7/genomics-reporting/branches/switch_structdefs/StructureDefinition-variant.html - note the StructureDefinition-variant.html
The canonical URL didn't change, it really does seem to be just the html page name that changed. Anyone concerned with that? I am not, but if others are, perhaps there is a way to adjust it back to how we did it before?
Jamie Jones (Aug 05 2020 at 21:47):
I don't mind
Lloyd McKenzie (Aug 05 2020 at 22:29):
Feedback on fade-from-white on the #IG creation stream. It's new and easy enough to yank if people don't want it
Patrick Werner (Aug 06 2020 at 09:41):
Thanks @Kevin Power , awesome.
:construction_worker:
Kevin Power (Aug 06 2020 at 11:23):
Are we ready to merge the PR?
Jamie Jones (Aug 06 2020 at 12:26):
Looked accurate to me
Kevin Power (Aug 06 2020 at 12:44):
PR merged.
Bob Dolin (Aug 10 2020 at 15:56):
@Jamie Jones @Kevin Power It looks like the narrative portions of $find-subject-variants aren't rendering any more, maybe because of conversion to new template? Let me know if you want some help investigating.
Jamie Jones (Aug 10 2020 at 15:59):
Great catch Bob, if you'd like to view the updated file structure it is hopefully an easy fix-- some of the url formats changed when moving to the template. If you get stuck I can take a look as well, let me know
Kevin Power (Aug 10 2020 at 16:19):
@Lloyd McKenzie - With the new template, where should the artifact 'intro' and 'notes' files go (what folder), and how should they be named? I tried reviewing the guidance but didn't see specifics like naming and folder location?
Patrick Werner (Aug 10 2020 at 17:02):
The potential 'page' folder names supported by the template are:
pages (for the markdown or XHTML page content)
pagecontent (same purpose as pages - use whichever name you prefer)
resource-docs (intended for -intro and -notes files -see below for more details.
images (for jpg, png and other image files - or any binary content that should be copied to the published website.
Kevin Power (Aug 10 2020 at 17:07):
OK @Patrick Werner , nice. Looks like you found that here - however, when I click the 'see below' link, I get a 404?
Anyway, maybe that gives the folder? The files for the operation were in the 'pagecontent' folder, but they are not being pulled in, so perhaps it is a file naming problem?
Kevin Power (Aug 10 2020 at 17:08):
and it is a file naming. With the new way we are doing it, and having the 'type of resource' prefixing the files now, I needed to add 'operationdefinition-' to the beginning of these files as well. They pulled in from the 'pagecontents' folder just fine.
But, given the guidance above, I will try putting them into a folder called 'resource-docs'
Patrick Werner (Aug 10 2020 at 17:17):
sorry, was in a hurry. Yes the link to see below is broken, but the content still there. I'm assuming the ig publisher only scans for intros and notes in resource-docs folders.
Kevin Power (Aug 10 2020 at 17:35):
Actually, no. I renamed the files to include 'operationdefinition-' to start the name, like 'operationdefinition-find-subject-variants-intro.xml', put them in the 'pages' folder, and the extra content pulled in just fine.
I created a folder for 'resource-docs' and put the appropriately named files in that folder, and it didn't work.
Put them back into the 'pages' folder, and it worked just fine again.
It is possible I did something wrong with the 'resource-docs' folder, but I don't have time to troubleshoot further. I will push up a fix shortly.
Patrick Werner (Aug 10 2020 at 17:41):
thank you!
Kevin Power (Aug 10 2020 at 18:04):
Welp, no idea why, but the operation 'intro' page did pull in after the cloud build, but it worked fine for me locally? Interesting, the same fix I applied did work for intro and notes we have for 'region-studied' and 'variant'
From cloud build:
image.png
Local build:
image.png
One last try, I noticed a 'case' difference in the file names, will try to make that consistent and see what happens, but won't have time to try much else.
Kevin Power (Aug 10 2020 at 18:22):
And luckily that worked, so I think we should be all good now. @Bob Dolin you wanna confirm?
Bob Dolin (Aug 10 2020 at 18:24):
@Kevin Power Thanks very much, it looks just right.
Jamie Jones (Aug 10 2020 at 18:43):
Great work! Glad to see those descriptions rendering again on variant and region-studied! I'll be looking at proposing some updates to them based on tomorrow's votes as well :)
Kevin Power (Aug 10 2020 at 18:44):
The block vote isn't tomorrow, it is next Tuesday. I didn't get the block out in time to vote this week.
Lloyd McKenzie (Aug 23 2020 at 18:52):
Sorry for the slow response - was on vacation for a bit. The filenames for the -intro and -notes are [artifacttype]-[id]-[suffix].[extension] where artifact type is the artifact in lower case (e.g. valueset), the id is the resource id, the suffix is 'intro' for introduction and 'notes' for notes. The extension is either md or xml depending on whether it's markdown or xhtml. The location can either be pages or pagecontent (with other pages) or if you like them to be separate, you can also stick them in a folder called intro-notes, though that last one isn't documented yet. If anyone has time to submit a pull request to update the 'guidance' IG with this info, that'd be awesome...
Kevin Power (Aug 23 2020 at 22:47):
Not sure what is going on, but I tried the naming as all lowercase, put them into intro-notes and it built and worked great locally. However, the cloud build didn't find the intro and note files. I am trying a couple of other things.
Kevin Power (Aug 23 2020 at 23:54):
Got it fixed finally, and PR for the guidance IG update:
https://github.com/FHIR/ig-guidance/pull/8. (@Lloyd McKenzie - are you the one to review?)
Last updated: Apr 12 2022 at 19:14 UTC
