Style guides Markup guide

Markup guide

General guidelines

If you document contains a toctree of children documents, it should be in its very beginning, below the h1 header.

List all the external links and roles involved in each document in its beginning: below the h1 header or toctree.

Remember carriage return and left indents: the reStructuredText/Sphinx syntax is very sensitive to line breaks and indents. Most directives must be indented with at least two spaces, relative to the spaces already implied by their current nesting level. A missing empty line results in the red build with a syntax error.

See also

reStructuredText markup specification

Sphinx official documentation

Paragraphs

Paragraphs are delimited by an empty line:

The first paragraph.

Another paragraph.

When a paragraph contains more than one sentence, add a line break after each sentence:

This is the first sentence in a paragraph.
This is the second sentence in it.

This is another paragraph.

In preview and on the website, such text appears without extra line breaks:

This is the first sentence in a paragraph. This is the second sentence in it.

This is another paragraph.

This makes it much easier to review commits, since only the sentences that have been edited are highlighted on GitLab, instead of the entire paragraphs. Moreover, this makes it easier to understand the shape and structure of the text — and keep your sentences short.

Note

We don’t follow the rest of the semantic line breaks convention: don’t use extra line breaks when outlining markup elements and paragraphs contained in tables and lists.

Headings

h1—h4

The heading text is left-indented with two double spaces:

################################################################################
    Heading 1
################################################################################

Paragraph text.

================================================================================
    Heading 2
================================================================================

Paragraph text.

--------------------------------------------------------------------------------
    Heading 3
--------------------------------------------------------------------------------

Paragraph text.

********************************************************************************
    Heading 4
********************************************************************************

Paragraph text.

Don’t use more than four nesting levels for headings (where H1 is a document title).

One reason for this is that a document with a lot of nested headings is difficult to navigate. This might also indicate that you need to structure information is some other ways.

Rubrics

Instead of placing another h3-h4 heading, you can always consider rubrics, of which this one is a prime example. The rubric directive is declared as follows:

.. rubric:: Rubrics

Paragraph text.

You can add rubrics under any preceding heading to keep the document tree short. Visually, rubrics are always rendered in the same way, regardless of their position relative to parent headings.

In other aspects, rubrics are similar to regular headings:

• they require no additional indentation for nested contents

• you can add an anchor TBD to a rubric when you need to refer to it throughout documentation

Formatting

The available text format options are pretty straightforward:

**This text is bold**

*This text is italic (and hard to follow)*

``This text is monospace``

Lists

Open each list with a short introduction that explains the list contents to readers and provides some context to it. You can end the intro with a colon or period, as long as you keep it that way across your project.

Don’t add left indents to lists. Unless nested, a list should be left-aligned with the main text.

To separate lists from the main text, insert empty lines. Don’t add empty lines between list items.

Numbered lists

Use numbered (ordered) lists to describe a strict sequence of actions, implying that list items cannot be swapped or skipped.

With numbered lists, always put a period at the end of each item:

Here is a numbered list example:

1. The first item.
2. The second item.
3. The third item.

Note

Instead of manually typing item numbers, the rST/Sphinx syntax allows you to mark list items with a hash sign #. On a webpage, these characters will be rendered as sequential numbers.

However, this feature is to be avoided, as it doesn’t work properly for elaborated lists that have nested levels or insertions (such as admonitions or code snippets).

Bullet lists

Use bullet (unordered) lists whenever the order of items is random or not important.

With shorter bullet lists, you can do without capitalization and periods for list items:

Here is a bullet list example:

- the first item
- the second item
- the third item

Nested lists

To indicate nested lists, use additional indentation by adding a double space to the nesting level of the main list.

Similar to any other list, add an empty line to separate a nested list from the parent list body:

Here is a nested list example:

1. The first item.
2. The second item.
3. The third item, which turns out to have a nested list:

  - some nested item
  - some nested item

4. The fourth and the closing item.

Tables

For tables, use the list-table directive:

.. list-table::
  :header-rows: 1
  :widths: 20 45 35

  * - Order            /* Header row */
    - Description
    - Flags

  * - ``Limit``        /* 1st row */
    - Limit order
    - ``isLimit`` is ``true``, ``isStop`` is ``false``, ``isFok`` is ``false``

  * - ``Market``       /* 2nd row */
    - Market order
    -                  /* This cell is empty */

This markup translates into a table that looks as follows:

Order	Description	Flags
Limit	Limit order	isLimit is true, isStop is false, isFok is false
Market	Market order

Remember to update the widths values upon adding new columns.

Declare empty cells as any other cells.

Images

For images, use the image directive:

.. image:: ../common/img/main-menu.png
  :scale: 40%
  :alt: Creating a merge request

When adding a large image:

1. Crop it to reduce the image dimensions. You can edit out all extraneous parts which don’t add up to the useful information that the image is supposed to convey.

2. Set the image scale to 40%. This way a reader can click the image thumbnail on the page to view it in the full size.

Important

Don’t forget to specify the alt option, describing the illustration in simple terms. This improves the page accessibility and helps the search engine to parse the page contents.

Code snippets

To insert code snippets, use the literalinclude directive:

.. literalinclude:: ../common/snippets/placeOrder.js
  :language: javascript
  :linenos:

Snippets are stored in separate files located in the common/snippets directory.

The linenos flag, which is used for line numbering, is not used for JSON files.

For occasional snippets (such as in this guide), use the code-block directive:

.. code-block:: c

  // Here is some sample code in C#.
  namespace HelloWorld
    {
      class Hello {
        static void Main(string[] args)
          {
            System.Console.WriteLine("Hello World!");
          }
      }
    }

Comments

To add private comments to a document for other reviewers or for yourself (when you want to keep your notes in a document for further clarification with the developers team), use the .. todo:: directive.

This line appears in the published document.

.. todo::

  This comment is private.
  It is not visible on the webpage.

For the comment not to appear in the rendered document and become available to the public, the todo extension must be listed in the project conf.py file.

Commenting out

At present, you can only comment out each line one by one, by adding two dots followed with a whitespace before it:

.. This line is commented out and doesn't appear on the webpage.
.. This line as well...
.. And this one also...

Escaping special characters

To insert a short fragment of text that uses the Sphinx syntax, enclose it with double back quotes:

This text is rendered in monospace and *as is*. All markup elements are **ignored**.

The escape character is backslash:

These /``quotes/`` must appear in preview as such.

Links

External links

To refer to an external webpage in a document, use the following syntax:

Refer to `PrimeXM Help Center <https://help.primexm.com/>`_.

Cross-references

When working on a document, you might need to refer to some parts of other documents from this project, or to other sections of the document at hand, which is a good way to take the project documentation to the next level, making it more coherent and easy to navigate.

Important

Before adding links to other documents from the same project, consult your Lead Technical Writer to ensure that these documents can be cross-referenced (that they aren’t deployed in separate bundles when compiling client documentation).

Internal links

At present, the autosectionlabel extension is enabled for all projects. When referencing a section of a document from the same project, use the following syntax:

:ref:`document name:section name`

…where:

• document name — the file name (without extension, such as .rst or .txt)

• section name — the document section (case-sensitive)

For example:

:ref:`user-guide:Users`
:ref:`how-tos:How to Grant Access to Your Wallet`

To provide custom text to a link, use the following syntax:

:ref:`display text<document name:section name>`

For example:

:ref:`deposit object<api-reference:Deposit Object>`

Anchors

All headings can be referenced as such, by their text TBD Headings, without the need to provide additional anchors.

To be able to refer to a rubric or some other part of your document, you can place an anchor before it:

.. _`Rubric anchor`:

.. rubric:: Custom rubric

Paragraph text.

Then, you can refer to this anchor in a usual way:

To learn more, refer to Rubric anchor *TBD*.

When referring to an anchor, you don’t need to additionally specify the document name.

Anchor names must be unique within the project.

Links to documents from other projects

TBD

Admonitions / Notices

When deciding whether to add an admonition/notice, follow some common guidelines.

The rule of thumb is to use admonitions as a last resort, to convey information that is customary in the current context.

.. note::

  This action can be performed only by users with certain permissions.

.. important::

  This action cannot be undone.

.. attention::

  This action poses serious security issues. Avoid it when possible.

.. seealso::

  This admonition is used to group links to the related documents and articles.

Here is how it looks on a webpage:

Note

This action can be performed only by users with certain permissions.

Important

This action cannot be undone.

Attention

This action poses serious security issues. Avoid it when possible.

See also

Cross-references TBD

Roles

Using roles, we can apply custom styles to specific text elements (change their font, background color and so on). This is most useful when working on API guides, since they need to provide various kinds of information in a concise format.

All the roles referenced in each document must be declared in the beginning of it. For example:

################################################################################
    Platform API
################################################################################

.. role:: get
.. role:: post
.. role:: put
.. role:: patch
.. role:: delete

In a document, element roles are indicated as follows:

:role-name:`formatted text`

For example:

:get:`GET` :base:`[base]`:endpoint:`/marketdata/instruments/`:path-param:`{instrument}`:endpoint:`/history`

The following roles are available:

Role	Scope	Element	Example
.. role:: get	API	An HTTP-verb	:get:`GET`
.. role:: post	API	An HTTP-verb	:post:`POST`
.. role:: put	API	An HTTP-verb	:put:`PUT`
.. role:: patch	API	An HTTP-verb	:patch:`PATCH`
.. role:: delete	API	An HTTP-verb	:delete:`DELETE`
.. role:: base	API	The base endpoint in a URL	:base:`[base]`
.. role:: endpoint	API	An endpoint	:endpoint:`/marketdata`
.. role:: path-param	API	A path parameter in an endpoint	:path-param:`{instrument}`
.. role:: param	API	A field/parameter in a list	:param:`id`
.. role:: type	API	The field/parameter type	:type:`string`
.. role:: ok	API	The HTTP-code 200	:ok:`200`
.. role:: error	API	An HTTP-code other than 200	:error:`404`
.. role:: required	All documents	A required field/parameter	:required:`*`
.. role:: comment	All documents	A commentary	:comment:`Obsolete`
.. role:: tag	All documents	A tag or label for an article. Can be used for quick searching	:tag:`merchant`

Expandable blocks

We use expandable blocks to hide long tables, nested fields and so on. Such blocks are displayed collapsed by default.

There is no ready solution for this feature in rST/Sphinx, so we use .. raw:: html directive to provide it. Inside the blocks, we use a regular rST/Sphinx markup, so you can make any information in you document expandable.

Simple blocks

By simple blocks we mean expandable blocks which are neither indented nor nested.

.. raw:: html

  <div class="accordion info">FIAT</div>   /* FIAT here is the name of our expandable block. */
  <div class="panel">                      /* This is a wrapper for our expandable text. */

.. list-table::                            /* Here begins a regular rST text. */
  :header-rows: 1
  :widths: 15 15 15 55

  * - Code
    - Alpha
    - Precision
    - Name

  * - 8
    - ALL
    - 2
    - Albanian lek

  * - 12
    - DZD
    - 2
    - Algerian dinar

  * - 32
    - ARS
    - 2
    - Argentine peso

.. raw:: html          /* As we "interrupted" our html with rST, duplicate the directive. */

  </div>               /* The only thing we need to do is to close the panel div. */

Note that in the example above the .. list-table:: directive has no left indets and is at the same level as the .. raw:: html directive. As a result, on a webpage our expandable block is also not indented and aligned with body text:

FIAT

Code	Alpha	Precision	Name
8	ALL	2	Albanian lek
12	DZD	2	Algerian dinar
32	ARS	2	Argentine peso

Nested blocks

You can make some blocks of text expandable on a webpage. For example, this way you can highlight the API structure by hiding nested fields and data structures that are of secondary interest to the readers.

When inserting an expandable block, left-align it with the level of the parent field description:

The **Advanced options** section
  Additional deposit settings.

  .. raw:: html

    <div class="accordion info">Expand fields</div>
    <div class="panel">

  **Label**
    The deposit name.

  **Tracking ID**
    Payment identifier in the client system.

  **Callback URL**
    URL for callback notifications on deposits. Such notifications may contain templates.

  **Required block confirmations for callback**
    Number of confirmations needed to receive an additional callback. If this field is not blank, two callbacks are sent: upon receiving the number of confirmations specified here and upon receiving the number of confirmations specified in the system settings.

  .. raw:: html

    </div>

The **Transactions** section
  A list of transactions. Transactions IDs are links to transfers details.

On a webpage, expandable blocks containing nested fields are left-aligned with parent fields:

The Advanced options section

Additional deposit settings.

Expand fields

Label

The deposit name.

Tracking ID

Payment identifier in the client system.

Callback URL

URL for callback notifications on deposits. Such notifications may contain templates.

Required block confirmations for callback

Number of confirmations needed to receive an additional callback. If this field is not blank, two callbacks are sent: upon receiving the number of confirmations specified here and upon receiving the number of confirmations specified in the system settings.

The Transactions section

A list of transactions. Transactions IDs are links to transfers details.

Note

Within expandable blocks, don’t wrap the lines with value lists even if they appear too long:

op_type

The type of the associated operation:

• 1 — a deposit/invoice

• 2 — a payout

• 5 — an incoming transfer linked to an exchange operation

• 9 — the writing-off costs associated with sending tokens; the amount of such transfer includes blockchain fee for withdrawal of tokens

• 14 — a direct deposit to the wallet address

• 16 — other due wallet fees

• 17 — an outgoing transfer linked to an exchange operation

It’s more convenient to always have all such blocks expanded. Use bullet lists for them.

Nested expandable blocks

You can also put expandable blocks inside one another. For this, you only need to properly increase the left indents, keeping all your blocks aligned with the correct level relative to the main document body.

**Event**
Event code.

.. raw:: html

  <div class="accordion info">Expandable Info</div>
  <div class="panel">

**Event handler workflow**
  The instruction to be executed upon event triggering.

**Enabled**
  If ``Enabled``, then the handler is active.

  .. raw:: html

    <div class="accordion info">Expandable Info</div>
    <div class="panel">

  **Event handler workflow**
    The instruction to be executed upon event triggering.

  **Enabled**
    If ``Enabled``, then the handler is active.

  .. raw:: html

    </div>

**Event handler workflow**
  The instruction to be executed upon event triggering.

**Enabled**
  If ``Enabled``, then the handler is active.

.. raw:: html

  </div>

ID

Event identifier in the system.

On a webpage, this looks as follows:

Event

Event code.

Expand fields

Event handler workflow

The instruction to be executed upon event triggering.

Enabled

If Enabled, then the handler is active.

Expand fields

Event handler workflow

The instruction to be executed upon event triggering.

Enabled

If Enabled, then the handler is active.

Event handler workflow

The instruction to be executed upon event triggering.

Enabled

If Enabled, then the handler is active.

ID

Event identifier in the system.

---

#onboarding #rules