Formatting Commands (Overview)¶

A reStructuredText document consists of body (or block-level elements) and it can be structured in sections. Sections are indicated by the title style (underlines and optional overlines). Sections contain body elements, subsections, or both. Some body elements contain other elements, such as lists with list items, which can also contain paragraphs and other body elements. Other elements, such as paragraphs, contain text and inline markup elements.

Note

The following information is compiled from the docutils documentation site and the Sphinx documentation site. Many thanks for this wonderful source of information.

Examples of body elements:

Paragraphs (and inline markup):
Paragraphs are separated by blank lines and are left aligned:
Paragraphs contain text and can include inline markup:: *emphasis*, **strong emphasis**, `interpreted text`, ``inline literals``, standalone hyperlinks (http://www.python.org), external hyperlinks (Python_), internal cross-references (example_), footnote references ([1]_), and substitution references (|product|).
Rendered example of above paragraph:

Paragraphs contain text and can include inline markup: emphasis, strong emphasis, interpreted text, inline literals, standalone hyperlinks (http://www.python.org), external hyperlinks (Python), internal cross-references (example), footnote references ([1]) and substitution references (CODESYS).

Types of lists:

Bullet lists:

- This is a bullet list.

- Bullets can be "*", "+", or "-".

Enumerated lists:

1. This is an enumerated list.

2. Enumerators may be arabic numbers, letters, or roman
   numerals.

Definition lists:

what
    Definition lists associate a term with a definition.

how
    The term is a one-line phrase, and the definition is one
    or more paragraphs or body elements, indented relative to
    the term.

Field lists:

:what: Field lists map field names to field bodies, like
       database records. They are often part of an extension
       syntax.

:how: The field marker is a colon, the field name, and a
      colon.

      The field body may include one or more body elements,
      indented relative to the field marker.

Literal blocks:

Literal blocks are either indented or line-prefix-quoted blocks,
and are indicated with a double-colon ("::") at the end of the
preceding paragraph (right here -->)::

    if literal_block:
        text = 'is left as-is'
        spaces_and_linebreaks = 'are preserved'
        markup_processing = None

Sphinx provides the capability of syntax coloring of literal blocks (code)

.. code-block:: <language>

   This construct introduces a literal block with syntax coloring
   regarding the defined programming language.

For literal blocks with code snippets written in the CODESYS ST language, it is possible to use:

.. code-block:: codesys

   /// Attempts to return the value of a boolean property.
   /// :return: ``xValue`` the boolean value of the property
   FUNCTION GetBooleanProperty : BOOL
   VAR_INPUT
       stKey: WSTRING;
   END_VAR

   /// This structure defines a special profile.
   /// :prefix: fp
   TYPE FLEXPROFILE :
   STRUCT
      id : INT := -1;
   […]
      buffer : WSTRING(255) := "☾ѺÐℰ$ẎS ḯṧ ♥ℯґƴ ¢☺◎ℓ";
   END_STRUCT
   END_TYPE

Depending on the current style sheet, the result could look like:

/// Attempts to return the value of a boolean property.
/// :return: ``xValue`` the boolean value of the property
FUNCTION GetBooleanProperty : BOOL
VAR_INPUT
    stKey: WSTRING;
END_VAR

/// This structure defines a special profile.
/// :prefix: fp
TYPE FLEXPROFILE :
STRUCT
   id : INT := -1;
[…]
   buffer : WSTRING(255) := "☾ѺÐℰ﹩УS ḯṧ ♥ℯґƴ ¢☺◎ℓ";
END_STRUCT
END_TYPE

Line Blocks:

Line blocks are useful where the structure of lines is significant.
This example illustrates continuation lines:

    | Lend us a couple of bob till Thursday.
    | I'm absolutely skint.
    | But I'm expecting a postal order and I can pay you back
      as soon as it comes.
    | Love, Ewan.

Block quotes:

Block quotes consist of indented body elements:

    This theory, that is mine, is mine.

    -- Anne Elk (Miss)

Different syntaxes for tables:

Grid tables are complete, but complex and verbose:

+------------------------+------------+----------+
| Header row, column 1   | Header 2   | Header 3 |
+========================+============+==========+
| body row 1, column 1   | column 2   | column 3 |
+------------------------+------------+----------+
| body row 2             | Cells may span        |
+------------------------+-----------------------+

Simple tables are easy and compact, but limited:

====================  ==========  ==========
Header row, column 1  Header 2    Header 3
====================  ==========  ==========
body row 1, column 1  column 2    column 3
body row 2            Cells may span columns
====================  ======================

List tables are extravagant:

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - 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!

Explicit markup blocks all begin with an explicit block marker, two periods, and a space:

Footnotes:

.. [1] A footnote contains body elements consistently
   indented by at least three spaces.

Hyperlink targets:
```
.. _Python: http://www.python.org

.. _example:
```
The “example” link above points to the target in this paragraph.

Titles are also targets. For example a implicit reference like Formatting Commands (Overview)

The Sphinx Package provides some additional options (roles) for hyperlinks (:ref:/:doc:):
```
:ref:`label <target>` create links between targets, even in different documents.
:doc:`label <path>` create links between different documents.
```
Directives:
```
.. image:: codesys.jpg
```
Will result in this example to this image:
Substitution definitions:
```
.. |product| replace:: CODESYS
```

Comments:

.. Comments begin with two dots and one space. Anything can
   follow, except for the syntax of footnotes/citations,
   hyperlink targets, directives, or substitution definitions.

The Markup Specification¶

The markup language reStructuredText is implemented in the parser of the word processing library “Docutils”. “Sphinx” is a tool for processing technical documentation. It takes advantage of the extensible nature of “reStructuredText” with its many extensions (for example, for automatic documentation generation from source text, displaying mathematical notation, and syntax highlighting). “reStructuredText” primarily consists of Direktives and Interpreted Text Roles. Depending on use, additional constructs (directives and roles) can be supplemented. These Extensions are prepared in the Python programming language. Therefore, it is not possible to provide a comprehensive list of the potential of “reStructuredText” at this point. However, the following references provide you with a solid overview.

CODESYS Specific Formatting Commands¶

The LibDoc Scripting Collection provides shortcuts to define the following:

Links to IEC-61131-3 type definitions

Library developers can use the substitution reference syntax like |iec-symbol| for referencing the location of the symbol declaration.

// | Access mode
// | File modes for opening a file.
//
// .. note::
//    For all ``*_PLUS`` modes, be aware that after being read from a file,
//    writing can be done only after a call of |SysFileGetPos| or
//    |SysFileSetPos|. If you called |SysFileWrite| right after |SysFileRead|,
//    then the file pointer might be on an invalid position.
//
//    Correct example::
//
//      SysFileRead();
//      SysFileGetPos();
//      SysFileWrite();
//
TYPE ACCESS_MODE : (
   AM_READ,       // Open an existing file with Read access. If the file does not exist, Open will fail.
   AM_WRITE,      // Create new file with Write access. If the file does exist, content will be discarded.
   AM_APPEND,     // Open an existing file with Append (write only) access. If file does not exist, Open will fail.
   AM_READ_PLUS,  // Open an existing file with Read/Write access. If the file does not exist, Open will fail.
   AM_WRITE_PLUS, // Create new file with Read/Write access. If the file exists, the content will be discarded.
   AM_APPEND_PLUS // Open an existing file with Append (read/write) access. If the file does not exist, Open will create a new file.
) UDINT;
END_TYPE

Description of a return value

If a return value of a function needs documentation, it is possible to write the last paragraph of the comment prefixed with the :return: sequence. The LibDoc Scripting Collection will transform this markup into a correct comment for the return value.

//  Check if end of file is reached
//
//  .. note::
//     End of file is checked only after a read operation with SysFileRead.
//     However, after a SysFileWrite or SysFileSetPos call, the function
//     returns ``ERR_FAILED`` (no end of file).
// :return: Returns the runtime system error code (see CmpErrors.library):
//    + ERR_OK: End of file reached at reading beyond the end of the file
//    + ERR_FAILED: No end of file reached
//    + ERR_PARAMETER: hFile is invalid
FUNCTION SysFileEOF : RTS_IEC_RESULT
VAR_INPUT
    hFile : RTS_IEC_HANDLE; // Handle of the file
END_VAR

Description of the prefix for a data type

If you want to define and document a specific prefix for an IEC structure, the last line of a comment can be prefixed with the :prefix: sequence. The LibDoc Scripting Collection will transform this markup into a correct reStructuredText element for documenting and indexing the new prefix defined in this way.
```
// | File Time
// | Timestamps of the specified file.
// :prefix: ft
TYPE SYS_FILETIME :
STRUCT
   tCreation : UDINT;         // Creation time of the file
   tLastAccess : UDINT;       // Time of as access to the file
   tLastModification : UDINT; // Time of last modification
END_STRUCT
END_TYPE
```
Referencing External Files

For working with external files included in the CODESYS project below the documentation comments, a method was introduced to easily retain the file name and path in the file system.

Each external file must have a unique name within the current project (for example, “MC_Stop_Timing”). This name can then be referenced in the comments by means of the following construction:
```
/// This diagram illustrates the behavior of MC_Stop_SML:
///
/// .. image:: @(MC_Stop_Timing) // see note (1)
///
/// The example below shows the behavior in combination with |MC_MoveVelocity_SML|.
///
/// a)  A rotating axis is ramped down with FB MC_Stop_SML.
/// b)  The axis rejects motion commands as long as MC_Stop_SML parameter ‘Execute’ = TRUE.
///     |MC_MoveVelocity_SML| reports an error indicating the busy `MC_Stop_SML` command.
///
/// .. image:: @(MC_Stop_Example) // see note (2)
///
```
1. results to “/../Images/MC_Stop_Timing.png”
2. results to “/../Images/MC_Stop_Example.png”
Note

Spaces in Path to Image.

The image directive can not handle spaces in its path parameter properly. If a external file is located inside a folder its name in the CODESYS project will be part of the path parameter. So it is not possible to use spaces inside this folder name.

Example:

Not possible:

Common Behaviour Model/Images/SC_ETrig.jpg

Possible:

Common-Behaviour-Model/Images/SC_ETrig.jpg