Introduction

The in-product API reference documentation for Totara was developed using a third-party tool called SpectaQL. SpectaQL is a NodeJS package which accepts the GraphQL schema (plus some optional metadata) and generates the HTML, CSS and JavaScript needed to display the API reference documentation.

In Totara's implementation, we insert the generated code within a Shadow DOM element within a Totara page in the product, which allows us to keep the SpectaQL and Totara styles isolated from each other to avoid stylesheet conflicts. We implement Totara-specific styling via a SpectaQL theme, and also make use of SpectaQL's data arrangement functionality.

We also mediate the output to allow us to perform permission checks before displaying it, and to allow us to dynamically replace the https://YOUR-SITE-URL URL with the actual Totara site URL within the documentation.

We ship the generated API reference documentation with our tagged releases, so for uncustomised sites on tagged versions the API reference documentation will automatically be available, and will reflect the API services available in that version.

For sites with code customisations that modify the API schema, developers will need to complete a build step to make the API documentation reflect their API changes. The API documentation page will automatically detect if the site schema differs from the released schema and display a warning if it is out of date.

The documentation build process

In order to build the API documentation you will need:

• A working php command with access to the site's dataroot folder

• A working node command with access to the site's dataroot folder

In many cases, you may have a single environment that meets both of these requirements, however, our Docker setup used by many developers keeps PHP and node in separate containers, so it is also possible they won't be available at the same time.

Two-step process (separate PHP and node environments)

Step 1: PHP build

The first step is to run a PHP build step, which completes the following tasks:

• Build the schema for each endpoint type and store it in a separate file (api/schema.{$endpoint_type}.graphqls) in the site's dataroot

• Build the metadata for each endpoint type and store it in a separate file (api/metadata.{$endpoint_type}.json) in the site's dataroot

• Build the site's component navigation structure (the name and title of all installed components) and store it in a file (api/nav.js) in the site's dataroot

The script is executed as follows (starting from the code root folder):

If called with the -q flag it will run as before, but only output the name of the directory containing the files without the informational string:

The output files should look something like this:

Step 2: Node JS build

Once step 1 is complete, it should be possible to trigger the Node JS build step, which makes use of the files generated in step 1 to build the documentation files.

This can be executed as follows (starting from the code root folder):

This will install the SpectaQL dependencies and execute a script which calls the command and generates the documentation build files in the appropriate code folder (extensions/api_docs/build/spectaql/). Once complete, you should find two files in that folder: out.html, which is a single file containing the HTML, CSS and JavaScript for the page, and out.json, which is a JSON file containing some metadata about the build step (used to detect schema changes).

The API reference documentation should now be available on your site via Quick access menu > Development > API > API Documentation.

Single-step process (combined PHP and node environments)

If PHP and node are both available in a single environment, you should be able to generate the documentation with a single command that passes the location of output from the PHP step to the node step as follows (starting from the code root folder):