The Reference section of Presidium should be reserved as a low-level reference for users. Typical components documented in the Reference section may include a client library or API specification. The process of importing documentation involves parsing a reference source and generating articles that are included in the generated site.

Where possible, reference documentation should be generated to ensure that your documentation is in sync with the system being documented.

Presidium supports the following documentation sources:

• OpenAPI3

For other sources that do not yet have an importer, documentation can be embedded into references.

Presidium includes a Golang tool (presidium-oapi3 for importing your OpenAPI 3 spec into Presidium documentation.

1. Add the presidium-oapi3 dependency to your site’s package.json or run npm install --save presidium-oapi3.
2. Add a script that invokes the tool.
3. Run npm run import-oapi whenever you need to update your API documentation.

{
    "scripts" : {
        "import-oapi" : "presidium-oapi3"
    },
}

Example:

$ npm run import-oapi convert -f <YOUR_API_SPEC> -o <THE_OUTPUT_DIRECTORY> -r <THE_PRESIDIUM_REFERENCE_URL>

The following options are available for presidium-oapi3:

A fallback approach to importing generated documentation is to embed documentation in an iframe. This approach is not recommended because items are not indexed or available on the main menu. However, it will work for certain cases when an importer is not yet available.

When possible, use a simple template when embedding documentation in an iframe.

To include documentation in an iframe:

1. Generate the static site documentation for your component.
2. Put the documentation in the /static folder so that it’s statically served. The Presidium convention is to place it under /static/import/{my-reference}.
3. Add a reference article to the Reference section:

---
title: My Reference
---

# foo.bar

<div>
    <iframe>
            src='/static/import/{my-reference}/foo/bar/package-summary.html'
    </iframe>
</div>

You can create multiple Markdown files for different components as required.