Updating Documentation

This documentation is generated using ESDoc, which automatically detects and generates documentation for methods, constants, functions etc. in the framework. This is under tabs Reference and Source at the top.

This manual also has custom pages (AKA under tab Home and what is on the left sidebar). These pages are generated using ESDoc's markdown -> HTML conversion feature, but some pages also use javascript to draw from config files in the framework in order to display all conditions, attributes etc.

These sections will describe how these custom pages work, and how to create new pages.

Project Structure of the Docs

• At root level:
  • docs folder - this is basically where everything documentation-related goes.
  • .esdoc.json - this is the config file for ESDoc. This file must be updated whenever you're adding new pages or new scripts.
    • There are three plugins:
      • esdoc-standard-plugin - adding the address of the md file into the files array will let ESDoc convert the md file into html.
      • esdoc-inject-script-plugin - adding the address of any scripts into the scripts array will let ESDoc run these scripts across ALL html files.
      • esdoc-inject-style-plugin - adding the address of any style scripts into the styles array will make the CSS available across ALL html files.
• Inside docs folder:
  • manual folder - this is where we add any new css, images, pages, or scripts.
  • You can IGNORE everything else, we are only touching the manual folder as everything else is automatically generated by ESDoc.

Dynamic Sections

Some creative hacking was involved to get ESDoc to draw from the data from the config files in the framework. This means that as devs add new conditions, attributes etc. into the config files, the documentation will also get automatically updated.

1. The main .md files that draw from config are conditions.md, experiments.md and supported_properties.md inside docs/manual/pages. These files just have the skeleton text (e.g. no tables).
2. The docs/manual/scripts/view-controller.js script:
   • Forcibly injects CDN JQuery + Bootstrap (which ESDoc could not do naturally)
   • Calls the renderer scripts depending on HTML id tag
3. Anything ending in -renderer.js inside docs/manual/scripts draws from the config files, creates all HTML tables and appends them to the page.
4. Note that in .esdoc.json, under the esdoc-inject-script-plugin, we include the config AND renderer scripts so they can be run throughout the docs.

Creating New Pages

1. Inside docs/manual/pages create a new markdown file. Write all your content using markdown syntax.
2. In .esdoc.json, add the page address into the array of files under the object with plugin name esdoc-standard-plugin.
3. ESDoc can now convert the markdown file into HTML. Run: ./node_modules/.bin/esdoc.

Updating Pages or Scripts

If you are changing ANY of the content inside docs/manual, or the config files from the framework have been updated, you must run this script so the documentation updates:

./node_modules/.bin/esdoc