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.

  1. text

    • bullet

    • bullet

  2. text

  3. text

    1. different numbering

    2. another item

Diagrams

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

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.

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

Alt text

Figure caption

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:

  1. Step A1

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

  1. Step A2

    1. substepA1

    2. substepA2

    3. substepA3

  1. Step A3

  2. Step A4

Another list which includes the steps from the previous list:

  1. Step B1

  1. Step A2

    1. substepA1

    2. substepA2

    3. substepA3

  1. substepB4

  2. 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

To link to doxygen macros, enums or functions use:

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.

Numbered sections

This is a special type of headings that will be automatically turned into steps of a large procedure. For usage example, see Installing the nRF Connect SDK.

First step

Content of first numbered heading.

Second step

Content of second numbered heading.

Third step

Content of third numbered heading.