Writing Documentation

HAPI FHIR Documentation Guide

This page describes various markdown features that can be used within HAPI FHIR and Smile CDR documentation.

Embedding URLs

A URL snippet can be performed using any of the following styles:

Single Line URL

```url
http://try.smilecdr.com:8000/Patient?name=Darma
```

Multiple URLs

This style includes several URLs in a single box, which can be more readable than using several separate snippets.

```url
http://try.smilecdr.com:8000/Patient?name=Darma
http://try.smilecdr.com:8000/Patient?name=Pixel
http://try.smilecdr.com:8000/Patient?name=Kona
```

Single URLs broken up over multiple lines for readability

```url
http://try.smilecdr.com:8000/Patient
   ?name=Darma
   &birthDate=2017
```

You can also include an HTTP verb in URL snippets:

```url
PUT http://example.com/Patient/123
```

Embedding Snippets

To embed a code snippet that is sourced from a source file elsewhere in the codebase, first create a snippet comment in your source file somewhere, e.g.:

// START SNIPPET: livebundle_example_earliestThreeByPathKeeper
function earliestThreeByPathKeeper() {
	// This is the path we use to determine to find the date to pick the most recent one
	let pathToOrderDate = 'period.start';

	return LiveBundleKeeperFactory.newEarliestByPath(pathToOrderDate, 3);
}
// END SNIPPET: livebundle_example_earliestThreeByPathKeeper

Then in the docs, use the following syntax to include that snippet (using the path to the file relative to the root of the project):

```javascript
{{snippet:file:cdr-persistence/src/test/resources/example_livebundle_rules.js|livebundle_example_toggleBySearchKeeper}}
```

Manually Setting Section IDs

By default, section IDs are generated using lowercased H1 text with whitespace replaced by -. For example:

# This is a section

This will result in the HTML:

<a name="this-is-a-section"/>
<h1>This is a section</h1>

You can manually set the anchor name by adding a manual anchor name tag in your markdown, as follows:

<a name="my-section"/>

# This is a section

This will result in the HTML:

<a name="my-section"/>
<h1>This is a section</h1>

Referencing Enums

Use the following custom tag in order to get compile-time checking of enum values.

<cdr:enum cdr:class="com.company.EnumClassName" cdr:name="ENUM_VALUE"/>

Automatic Expiry / Failure

Sometimes it is useful to write a comment about how something is new and subject to change, but you don't want that comment to stick around forever. In this case you can create a little "time bomb" that will fail the docs generation after a few releases.

To do this add a tag like the following. Note that we drop the point release from the version, and that the build will fail as soon as the version is incremented to a minor version after the given string.

HAPI FHIR:

<cdr:fail cdr:afterVersion="4.2"/> 

Smile CDR:

<cdr:fail cdr:afterVersion="2020.08"/> 

Referencing Menus

When referencing navigating through menus, use the following syntax. The -> part will be transformed into a stylized chevron during rendering.

File -> Options -> Add File...

Example Tables

Example tables show a document or payload, with annotated sections highlighted.

See the JSON Encoding example here to see what this looks like: https://smilecdr.com/docs/fhir_standard/fhir_introduction.html#the-json-format

Example tables start with a line containing only {{START-EXAMPLE-TABLE}} followed by a line containing only ```.

They end with a line containing only ``` followed by a line containing only {{END-EXAMPLE-TABLE}}.

Within the document, annotated sections are demarcated by a line containing {{START-LABEL: some annotation text}} and ended by a line containing {{END-LABEL}}. If an annotated section is immediately followed by another annotated section, you can skip the END-LABEL line.

The following source shows an example:

{{START-EXAMPLE-TABLE}}
```
{
  "resourceType": "Observation",
  "id": "O1",
  "contained": [
{{START-LABEL: Contained Patient resource within Observation resource}}
    {
      "resourceType": "Patient",
      "id": "pat",
      "name": [ {
        "family": "Smith",
        "given": [ "John" ]
      } ], 
      "birthDate": "1980-07-22"
    } 
{{END-LABEL}}
  ],
  "subject": {
{{START-LABEL: Fragment reference to contained resource}}
    "reference": "#pat"
{{END-LABEL}}
  },
  "status": "final",
  "code": {
    "coding": [ {
      "system": "http://loinc.org",
      "code": "29463-7",
      "display": "Body Weight"
    } ]
  },
  "valueQuantity": {
    "value": 67.1,
    "unit": "kg",
    "system": "http://unitsofmeasure.org",
    "code": "kg"
  }
}
```
{{END-EXAMPLE-TABLE}}