Writing developer docs¶

This site is built by MkDocs and uses the Material for MkDocs theme.

You can serve documentation locally with the docs.serve invoke task.

Organization¶

The site structure is defined by the nav key in the mkdocs.yml file.

When adding new pages, first think about what it is exactly that you are trying to document. For example, if you intend to write about something everyone must follow as a standard practice it would be classified as a guideline whereas a short piece about performing a particular task would be a how-to.

After deciding the kind of content, strive to further segment the page under logical groupings for easier navigation.

Line continuations¶

For prose where the rendered content should have no line breaks, always keep the Markdown on the same line. This removes the need for any stylistic enforcement and allows for IDEs to intelligently wrap as usual.

Tip

When you wish to force a line continuation but stay within the block, indent by 2 spaces from the start of the text and end the block with a new line. For example, the following shows how you would achieve a multi-line ordered list item:

Markdown

1. first line

     second line

1. third line

Rendered

first line

second line
third line

Emphasis¶

When you want to call something out, use admonitions rather than making large chunks of text bold or italicized. The latter is okay for small spans within sentences.

Here's an example:

Markdown
```
!!! info
    Lorem ipsum ...
```
Rendered

Info

Lorem ipsum ...

Links¶

Always use inline links rather than reference links.

The only exception to that rule is links that many pages may need to reference. Such links may be added to this file that all pages are able to reference.

Abbreviations¶

Abbreviations like DSD may be added to this file which will make it so that a tooltip will be displayed on hover.