Skip to main content

Writing documentation

Once your new ETM feature is ready, it's important to write documentation so that visitors understand how to use it, and fellow modelers and developers can see how it works.

Getting started​

Documentation is split into three sections:

  • For users. These are aimed at those who visit the ETM, and should explain how to use the website, providing details on how features work from the perspective of a visitor. These documents are located in docs/main.

  • For contributors. These docs are aimed at Quintel employees as well as outside modelers and developers who may wish to contribute. This sections should contain descriptions of how features are implemented and guides for using them in ETSource. These documents can be found at docs/contrib.

  • API reference. This section is aimed at the growing number of users who wish to interact with the ETM directly through the JSON API, rather than the website. These documents can be found at docs/api. API endpoint parameters are defined in JavaScript at data/api.

Authoring documentation​

All documentation is written in Markdown. For an overview of supported features, see the Docusaurus docs. Markdown file names should be all lowercase with spaces replaced with dashes.

Titles and YAML​

The start of your document must contain YAML front-matter with at least a title attribute:

---
title: My first document!
---

Document contents start here. No need to add the page title; Docusaurus
will use the above `title` attribute.

If your document title is quite long and will not fit neatly on the sidebar, consider adding a shorter label to be used only on the sidebar:

---
title: My second document, whose title is clearly too long
sidebar_label: Second document
---

Content here.

Linking to other documents​

Use Markdown links to link to another document. These should be relative to the current document: include the ".md" suffix as this will allow the documents to be navigated on GitHub. See Docusaurus → Referencing other documents.

Linking to 'docs/main/cost-calculations.md' from 'contrib/hi.md'
[My link text](../main/cost-calculations.md)

Linking to headers and sections​

To link to a section in the same document, you must find the header you wish to link to, then convert all characters to lowercase and swap spaces for dashes. The string is then prefixed with a "#".

Linking to the 'Electricity production' header
[My link text](#electricity-production)

To link to a section in another document, start with the link to the other document then add the header link:

Linking to 'Electricity production' on 'Cost calculations'
[My link text](../cost-calculations.md#electricity-production)
Caution when changing headers!

As section IDs are automatically generated from the header text, changing the title of a section in a Markdown document will break any existing links to that header. Be sure to search for the outdated references and update them as necessary: git grep "my-old-title"

Using images​

Images can be added to static/img/docs and should be referenced using Markdown from the absolute web root when published, i.e., prefixed with a "/" and without the "static/":

![My image alt. text](/img/docs/total_capacity.jpg)
Image compression

Please compress images with a tool like ImageOptim prior to committing.

Adding to the sidebar​

Documents do not automatically appear in the sidebar. Instead, they must be added to the sidebar.js in the project root. This file contains the definitions for three sidebars:

  • mainSidebar used by the "For Users" section.
  • contribSidebar used by the "For Contributors" section.
  • apiSidebar used by the "API Reference" section.

Find the category most appropriate for your document (or add a new one), then add the path of the file minus the "docs/" prefix and ".md" suffix to the items list. For example, if adding a document located at docs/main/new-costs.md, which you wish to appear below the "Cost calculations" document, add the following line to the "Costs" category:

{
  type: "category",
  label: 'Costs',
  items: [
    'main/costs',
    'main/cost-calculations',
    'main/new-costs',
    'main/costs-imported-electricity',
    'main/heat-and-electricity-cost',
    'main/heat-infrastructure-costs',
  ],
},

All documents are indexed by Algolia DocSearch once per day; you do not need to do anything. It may take up to 24 hours for your changes to be reflected in the index.

Pushing your changes​

Editing documents does not require you to install anything. You may edit and push changes to the Markdown files, with the website being built and deployed automatically when pushed to the master branch.

Previewing changes

Make your changes on a separate branch and create a pull request on GitHub. Netlify will shortly thereafter comment on your PR with a preview of the website. Alternatively, install the prerequisites for Docusaurus on your machine and run yarn start.