Update to documentation regarding narrative generation; (#4521)

Providing changelog;

Co-authored-by: peartree <etienne.poirier@smilecdr.com>

hapi-fhir-base/src/main/resources/ca/uhn/fhir/narrative/OperationOutcome.html

@@ -11,7 +11,7 @@
 			<tr th:each="issue : ${resource.issue}">
 				<td th:text="${issue.severityElement.value}" style="font-weight: bold;"></td>
 				<td th:text="${issue.location}"></td>
-				<td th:text="${issue.diagnostics}"></td>
+				<td th:narrative="${issue.diagnostics[0]}"></td>
 			</tr>
 		</table>
 	</div>

hapi-fhir-docs/src/main/java/ca/uhn/hapi/fhir/docs/Narrative.java

@@ -42,7 +42,7 @@ FhirContext ctx = FhirContext.forDstu2();
 ctx.setNarrativeGenerator(new DefaultThymeleafNarrativeGenerator());
 
 // Encode the output, including the narrative
-String output = ctx.newJsonParser().setPrettyPrint(true).encodeResourceToString(patient);
+String output = ctx.newXmlParser().setPrettyPrint(true).encodeResourceToString(patient);
 System.out.println(output);
 //END SNIPPET: example1
 

hapi-fhir-docs/src/main/java/ca/uhn/hapi/fhir/docs/NarrativeGenerator.java

@@ -21,6 +21,7 @@ package ca.uhn.hapi.fhir.docs;
  */
 
 import ca.uhn.fhir.context.FhirContext;
+import ca.uhn.fhir.model.dstu2.resource.Patient;
 import ca.uhn.fhir.narrative.CustomThymeleafNarrativeGenerator;
 
 @SuppressWarnings("unused")
@@ -33,7 +34,11 @@ FhirContext ctx = FhirContext.forDstu2();
 String propFile = "classpath:/com/foo/customnarrative.properties";
 CustomThymeleafNarrativeGenerator gen = new CustomThymeleafNarrativeGenerator(propFile);
 
+Patient patient = new Patient();
+
 ctx.setNarrativeGenerator(gen);
+String output = ctx.newJsonParser().encodeResourceToString(patient);
+System.out.println(output);
 //END SNIPPET: gen
 
 	

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/changelog/6_4_0/450-update-to-narrative-generation-documentation.yaml

@@ -0,0 +1,5 @@
+---
+type: fix
+issue: 4520
+jira: SMILE-4406
+title: "Updating documentation related to narrative generation."

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/model/narrative_generation.md

@@ -2,7 +2,7 @@
 
 HAPI provides several ways to add [Narrative Text](http://hl7.org/fhir/narrative.html) to your encoded messages.
 
-The simplest way is to simply place the narrative text directly in the resource via the `setDivAsString()` method.
+The simplest way is to place the narrative text directly in the resource via the `setDivAsString()` method.
 
 ```java
 {{snippet:classpath:/ca/uhn/hapi/fhir/docs/Narrative.java|simple}}
@@ -18,7 +18,7 @@ HAPI's built-in narrative generation uses the [Thymeleaf](http://www.thymeleaf.o
 
 ## A Simple Example
 
-Activating HAPI's built-in narrative generator is as simple as calling [setNarrativeGenerator](/hapi-fhir/apidocs/hapi-fhir-base/ca/uhn/fhir/context/FhirContext.html#setNarrativeGenerator(ca.uhn.fhir.narrative.INarrativeGenerator).
+Activating HAPI's built-in narrative generator is as simple as calling [setNarrativeGenerator](/hapi-fhir/apidocs/hapi-fhir-base/ca/uhn/fhir/context/FhirContext.html#setNarrativeGenerator(ca.uhn.fhir.narrative.INarrativeGenerator)).
 
 ```java
 {{snippet:classpath:/ca/uhn/hapi/fhir/docs/Narrative.java|example1}}
@@ -79,13 +79,16 @@ vitalsigns.profile=http://hl7.org/fhir/StructureDefinition/vitalsigns
 vitalsigns.narrative=classpath:com/example/narrative/Observation_Vitals.html
 ```
 
-You may also override/define behaviour for datatypes and other structures. These datatype narrative definitions will be used as content within <code>th:narrative</code> blocks in resource templates. See the example resource template above for an example.
+You may also override/define behaviour for datatypes and other structures. These datatype narrative definitions will be used as content within <code>th:narrative</code> blocks in resource templates. See the [example above](#creating-your-own-templates).
 
 ```properties
 # You can create a template based on a type name
 quantity.dataType=Quantity
 quantity.narrative=classpath:com/example/narrative/Quantity.html
 
+string.dataType=String
+string.narrative=classpath:com/example/narrative/String.html
+
 # Or by class name, which can be useful for custom datatypes and structures
 custom_extension.class=com.example.model.MyCustomExtension
 custom_extension.narrative=classpath:com/example/narrative/CustomExtension.html
@@ -105,13 +108,13 @@ Thymeleaf has a concept called Fragments, which allow reusable template portions
 {{snippet:classpath:ca/uhn/fhir/narrative/narrative-with-fragment.properties}}
 ```
 
-The following template declares a fragment (this is `narrative-with-fragment-child.html` in the example above):
+The following template declares `Fragment1` and `Fragment2` as part of file `narrative-with-fragment-child.html`: 
 
 ```html
 {{snippet:classpath:ca/uhn/fhir/narrative/narrative-with-fragment-child.html}}
 ```
 
-And the following template uses it (this is `narrative-with-fragment-child.html` in the example above):
+And the following parent template (`narrative-with-fragment-parent.html`) imports `Fragment1` with parameter 'blah':
 
 ```html
 {{snippet:classpath:ca/uhn/fhir/narrative/narrative-with-fragment-parent.html}}

hapi-fhir-test-utilities/src/main/resources/ca/uhn/fhir/narrative/narrative-with-fragment.properties

@@ -4,6 +4,7 @@ bundle.resourceType        = Bundle
 bundle.style               = thymeleaf
 bundle.narrative           = classpath:ca/uhn/fhir/narrative/narrative-with-fragment-parent.html
 
+# Fragment template
 fragment1.fragmentName     = MyFragment
 fragment1.style            = thymeleaf
 fragment1.narrative        = classpath:ca/uhn/fhir/narrative/narrative-with-fragment-child.html