Cheat Sheet

This topic is not meant to be included in the output, but to serve as reference for common RST syntax and linking between doc sets.

RST syntax 

Simple Markup 

italics bold code

howtoemphasizeinsideaword

name or name

make

Install

ZEPHYR_MBEDTLS_NRF_MODULE_DIR (this is a name of the make variable)

$HOME (this is an environment variable)

Lists 

This is a bulleted list.
Another item.
1. This is a list.
2. More.
One more.

text
- bullet
- bullet
text
text
1. different numbering
2. another item

You can include Message Sequence Chart (MSC) diagrams in RST by using the .. msc:: directive and including the MSC content, using the syntax described for example here: http://www.mcternan.me.uk/mscgen/. Use validator at https://mscgen.js.org/ for syntax check. Example:

.. msc::
    hscale = "1.3";
    Module,Application;
    Module<<Application      [label="nrf_cloud_connect() returns successfully"];
    Module>>Application      [label="NRF_CLOUD_EVT_TRANSPORT_CONNECTED"];
    Module>>Application      [label="NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST"];
    Module<<Application      [label="nrf_cloud_user_associate()"];
    Module>>Application      [label="NRF_CLOUD_EVT_USER_ASSOCIATED"];
    Module>>Application      [label="NRF_CLOUD_EVT_READY"];
    Module>>Application      [label="NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED"];

This will generate the following output:

$msc { hscale = "1.3"; Module,Application; Module<<Application [label="nrf_cloud_connect() returns successfully"]; Module>>Application [label="NRF_CLOUD_EVT_TRANSPORT_CONNECTED"]; Module>>Application [label="NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST"]; Module<<Application [label="nrf_cloud_user_associate()"]; Module>>Application [label="NRF_CLOUD_EVT_USER_ASSOCIATED"]; Module>>Application [label="NRF_CLOUD_EVT_READY"]; Module>>Application [label="NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED"]; }$

Definition list 

term (up to a line of text)

Definition of the term, which must be indented

and can even consist of multiple paragraphs

next term

Description.

Glossary

See Glossary for usage.

Indentation 

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis elementum odio vel viverra malesuada. Cras aliquet libero non iaculis rhoncus.

Sed pulvinar augue a cursus mollis. Vivamus nec feugiat augue, sed vehicula purus. Fusce feugiat rutrum dui ut convallis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Pellentesque nec metus vitae felis porta accumsan eget non ipsum.

Etiam lacinia, sapien quis eleifend posuere,
urna eros porttitor lorem,
vitae faucibus libero diam sed nunc.
Maecenas vitae ornare est.
Phasellus nec molestie elit.

Nam hendrerit ex pretium, facilisis lectus sit amet, semper eros:

Curabitur at nulla velit. Ut turpis nunc, porttitor eu laoreet in, venenatis at quam. Morbi at nisl id nibh laoreet cursus ac vitae massa.

Tables 

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	…	…

We can create more complex tables as ASCII art:

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1 lsjdlfkj		column 3	column 4
body row 2	…	…	test spanning
body row 3	…	…	test spanning

Truth table for “not”
A	not A
False	True
True	False

Frozen Delights!
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!
Line-break example	x	First line Second line

Frozen Delights!
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

To force line-breaks in a table, use a line block:

First line

Second line

Tabs 

Example usage of tabs is to show how the same procedure works on different operating systems:

Windows tab

Toggle 

The .. toggle:: directive lets you create expandable sections. Useful to hide content that is potentially irrelevant to many customers.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Embedding media 

This is how you can embed a video:

In general, the .. raw:: html directive will process any HTML code provided in it.

Links 

Nulla aliquam lacinia risus eget congue. Morbi posuere a nisi id vulputate. Curabitur ac lacus magna. Aliquam urna lacus, ornare non iaculis vel, ullamcorper vel dolor. Nunc vel dui vulputate, imperdiet metus eget, tristique dui. Etiam non lorem vel magna dictum aliquam. Nunc hendrerit facilisis diam, non mollis leo commodo nec.

www.nordicsemi.com https://www.nordicsemi.com

Tables

override

Overriding link text

Use :ref: to link to IDs and :doc: to link to files.

If you have a link ID in links.txt that consists of only one word, you cannot have a heading anywhere that is the same. If you do, you’ll get an error about a duplicate ID in links.txt.

Notes and similar elements 

Note

This is a note.

Tip

This is a tip.

Important

This is important stuff.

Caution

This is a caution note. Use for things like security issues or to prevent major flaws in the application.

Warning

This is a warning. Do not overuse this. Use only to warn against device bricking, unrecoverable issues, or potential injury (when describing hardware).

Images 

Make sure to correctly specify the path to the image file. A slash at the beginning of the path indicates an absolute path and will link to the common image folder in doc/nrf. Starting the path without the forward slash indicates a relative path.

Math equations 

\[(a + b)^2 = a^2 + 2ab + b^2\]

Footnotes 

Integer ac ex lacinia [Ref1], tristique odio vitae, ullamcorper enim. Mauris aliquet rutrum justo eget dapibus. Nunc nec justo a nulla tristique accumsan. Integer sit amet porta mauris, quis aliquet [Ref2] justo. Ut et nulla interdum, facilisis lacus eu, consectetur libero. Cras faucibus ut turpis eu aliquam. Etiam feugiat, urna a lobortis aliquet, ex enim [Ref1] varius felis, et porta arcu felis vel odio. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer consectetur vel elit vel fringilla. Nam eu ultricies leo, a volutpat erat. Nam tempor dolor vel consequat aliquam. Maecenas ornare condimentum mattis. Aliquam tellus tortor, varius ac iaculis ut, tincidunt quis quam.

[Ref1] (1,2)

Footnote 1

[Ref2]

Footnote 2

Variables 

Curabitur nisl some Latin word, posuere auctor metus et, convallis varius turpis. Sed elementum rhoncus some Latin word, dictum posuere lectus.

Reuse 

To reuse text from the same or another file in the same doc set:

Include 1:

italics bold code

howtoemphasizeinsideaword

name or name

make

Include 2:

Note

If you get an error message when running west, update west to the latest version. See Troubleshooting West in the Zephyr documentation for more information.

To reuse text from another doc set:

Include 3:

Set up a command-line Zephyr development environment on Ubuntu, macOS, or Windows (instructions for other Linux distributions are discussed in Install Linux Host Dependencies)
Get the source code
Build, flash, and run a sample application

Select and Update OS

Include 4:

A Type 2 Tag can be read and re-written, and the memory of the tag can be write protected. The Type 2 Tag library implements a Type 2 Tag in read-only state. Read only means that the memory of the tag is write protected and cannot be erased (formatted) or re-written by the polling device.

You can also use ncs-include if you want to use the indentation options inside the nrf doc set:

Include 5 (similar to include 2, but improved indentation):: Note

If you get an error message when running west, update west to the latest version. See Troubleshooting West in the Zephyr documentation for more information.

See https://github.com/nrfconnect/sdk-nrf/commit/fa5bd7330538f6a12e059c9d60fa2696e48fcf3a for implementation and usage.

Tip

If you need a “start-after” text that occurs more than once inside a document, you can combine :start-after: with :start-line:. Sphinx will then use the first occurrence of the “start-after” text after the specified start line.

Shortcuts 

Defined in the shortcuts.txt file. Usage: nRF Connect SDK

They can be used for replacing single words but also for multiple paragraphs.

Including text inside a nested list 

List 1:

Step A1

Including the first three sub-list items of 2. Step A2 in the second list

Step A2
1. substepA1
2. substepA2
3. substepA3

Step A3
Step A4

Another list which includes the steps from the previous list:

Step B1

Step A2
1. substepA1
2. substepA2
3. substepA3

substepB4

substepB5

Including code snippets in RST 

To include a code snippet from a code file in an .rst file, you need to edit both.

Defining snippet in code file 

Use RST tags in the comments to enclose the code you want to become a snippet.

Use the following tag formatting:

* Starting tag: /** .. include_startingpoint_<name of file where the snippet goes>_rst_<number of snippet within the .c file> */
* Ending tag: /** .. include_endpoint_<name of file where the snippet goes>_rst_<number of snippet within the .c file> */

For example:

/** .. include_startingpoint_scan_rst_1 */
    static void scan_filter_no_match(struct bt_scan_device_info *device_info,
                 bool connectable)
{
    struct bt_conn *conn;
    char addr[BT_ADDR_LE_STR_LEN];
    if (device_info->adv_info.adv_type == BT_LE_ADV_DIRECT_IND) {
        bt_addr_le_to_str(device_info->addr, addr, sizeof(addr));
        printk("Direct advertising received from %s\n", addr);
        bt_scan_stop();

        conn = bt_conn_create_le(device_info->addr,
                     device_info->conn_param);

        if (conn) {
            default_conn = bt_conn_ref(conn);
            bt_conn_unref(conn);
        }
    }
}
/** .. include_endpoint_scan_rst_1 */

Including snippet in .rst 

To include the snippet you defined in a code file into an .rst file, use the following RST syntax:

.. literalinclude:: <path to the code file with the snippet>
   :language: <coding language, for example 'c', 'python', 'ruby'>
   :start-after: <opening tag of the snippet>
   :end-before: <closing tag of the snippet>

For example:

.. literalinclude:: ../../samples/bluetooth/central_hids/src/main.c
    :language: c
    :start-after: include_startingpoint_scan_rst_1
    :end-before: include_endpoint_scan_rst_1

Code blocks 

To manually type a block of code, you can use code-block:

python buildprog.py -c app -b debug -d both

You can also apply code highlighting as in the following examples:

Devicetree:

  &pinctrl {
      spi0_default_alt: spi0_default_alt {
          group1 {
              psels = <NRF_PSEL(SPI_SCK, 0, 10)>,
                      <NRF_PSEL(SPI_MISO, 0, 12)>,
                      <NRF_PSEL(SPI_MOSI, 0, 13)>;
          };
      };

      spi0_sleep_alt: spi0_sleep_alt {
          group1 {
              psels = <NRF_PSEL(SPI_SCK, 0, 16)>,
                      <NRF_PSEL(SPI_MISO, 0, 15)>,
                      <NRF_PSEL(SPI_MOSI, 0, 17)>;
              low-power-enable;
        };
      };
  };
};

Devicetree (alternative):

/ {
        chosen {
                ncs,dm-timer = &timer2;
        };
};

C:

static struct bt_mesh_model_pub pub_ctx;
static struct net_buf_simple pub_msg;
static uint8_t buf[BT_MESH_MODEL_BUF_LEN(MESSAGE_SET_OPCODE,
                                         MESSAGE_SET_MAXLEN)];

static int model_init(struct bt_mesh_model *model)
{
    model->pub = &pub_ctx;
    net_buf_simple_init_with_data(&pub_msg, buf, sizeof(buf));
    pub_ctx.msg = &pub_msg;

    return 0;
}

C++:

#include <zephyr/pm/device.h>

const auto * qspi_dev = DEVICE_DT_GET(DT_INST(0, nordic_qspi_nor));
if (device_is_ready(qspi_dev))
{
    // Put the peripheral into suspended state.
    pm_device_action_run(qspi_dev, PM_DEVICE_ACTION_SUSPEND);

    // Resume the peripheral from the suspended state.
    pm_device_action_run(qspi_dev, PM_DEVICE_ACTION_RESUME);
}

C++ (alternative):

struct Request : public sys_snode_t
{
   uint8_t priority;                     ///< Advertising request priority. Lower value means higher priority
   uint32_t options;                     ///< Advertising options: bitmask of BT_LE_ADV_OPT_XXX constants from Zephyr
   uint16_t minInterval;                 ///< Minimum advertising interval in 0.625 ms units
   uint16_t maxInterval;                 ///< Maximum advertising interval in 0.625 ms units
   Span<const bt_data> advertisingData;  ///< Advertising data fields
   Span<const bt_data> scanResponseData; ///< Scan response data fields
   OnAdvertisingStarted onStarted;       ///< (Optional) Callback invoked when the request becomes top-priority.
   OnAdvertisingStopped onStopped;       ///< (Optional) Callback invoked when the request stops being top-priority.
};

Kconfig:

EXT_API = MY
id = 0xBEEF
flags = 0
ver = 1
source "${ZEPHYR_BASE}/../nrf/subsys/fw_info/Kconfig.template.fw_info_ext_api"

cmake:

if(CONFIG_NRF_MODEM_LIB_TRACE)

zephyr_library()
# Only add 'custom' backend to compilation when selected.
zephyr_library_sources_ifdef(
  CONFIG_NRF_MODEM_LIB_TRACE_BACKEND_MY_TRACE_BACKEND
  path/to/my_trace_backend.c
)

endif()

yaml:

ncs:
  upstream-url: https://...
  upstream-sha: GIT_SHA
  compare-by-default: <true|false>

Python:

class OpenThread(OpenThreadTHCI, IThci)

Linking between doc sets 

Read out an objects.inv file:

python3 -m sphinx.ext.intersphinx objects.inv

Doxygen 

We usually include doxygen groups:

.. doxygengroup:: group_name
   :project: nrf
   :members:

See the breathe documentation for information about what you can link to.

To link to doxygen macros, enums or functions use:

BT_HIDS_INFORMATION_LEN
bt_hids_init()
bt_gatt_dm
slm_data_handler_t
at_param_type (for the whole list)
PEER_STATE_CONN_FAILED (for a list item)
ble_peer_event.state

For C++ elements:

mbedtls_entropy_init()
bt_mesh_time_tai
bt_mesh_time_role
request_msg_recv

Kconfig 

Link to library Kconfig options using CONFIG_NORDIC_SECURITY_BACKEND.

For more information on how to link to application-specific configuration options, see Configuration options. Example: CONFIG_UDP_DATA_UPLOAD_FREQUENCY_SECONDS.

Linked RST project 

Zephyr Project Documentation - link to a page

Getting Started Guide - link to an ID

Heading lvl 4

Lower hierarchy section.

Heading lvl 5

Even lower hierarchy section.