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.

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:

  1. Bullet lists :

     - This is a bullet list.
     
     - Bullets can be "*", "+", or "-".

  2. Enumerated lists :

     1. This is an enumerated list.
     
     2. Enumerators may be arabic numbers, letters, or roman
       numerals.

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

  4. 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:

  1. 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        |
     +------------------------+-----------------------+

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

  3. 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 para­graph.

    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 Exten­sions are prepared in the Python programming language. Therefore, it is not possible to provide a comprehensive list of the potential of "reStruc­turedText" at this point. However, the following references provide you with a solid overview.

• reStructuredText Markup Specification

• Direktives

• Interpreted Text Roles

• reStructuredText Standard Definition Files

• Sphinx Markup Constructs

• Sphinx Extensions

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 (CDS-41939)

  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 construc­tion:

  /// 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