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
```

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...