Documentation formatting¶

It is possible to use simple HTML formatting with `test suite`__, `test case`__ and `user keyword`__ documentation and `free test suite metadata`_ in the test data, as well as when `documenting test libraries`__. The formatting is similar to the style used in most wikis, and it is designed to be understandable both as plain text and after the HTML transformation.

Representing newlines
- Newlines in test data
- Documentation in test libraries
Paragraphs
Inline styles
URLs
Custom links and images
Section titles
Tables
Lists
Preformatted text
Horizontal ruler

Representing newlines ¶

Newlines in test data ¶

When documenting test suites, test cases and keywords or adding metadata to test suites, newlines can be added manually using the `literal newline character sequence`__ (n).

*** Settings ***
Documentation    First line.\n\nSecond paragraph, this time\nwith multiple lines.
Metadata         Example    Value\nin two lines

Adding newlines manually to a long documentation takes some effort and extra characters also make the documentation harder to read. Starting from Robot Framework 2.7, this is not required as newlines are inserted automatically between `continued documentation and metadata lines`__. In practice this means that the above example could be written also as follows.

*** Settings ***
Documentation
...    First line.
...
...    Second paragraph, this time
...    with multiple lines.
Metadata
...    Example
...    Value
...    in two lines

No automatic newline is added if a line already ends with a literal newline or if it ends with an `escaping backslash`__. If documentation or metadata is defined in multiple columns, cells in a same row are concatenated together with spaces. This kind of splitting can be a good idea especially when using the `HTML format`_ and columns are narrow. Different ways to split documentation are illustrated in the examples below where all test cases end up having the same two line documentation.

*** Test Cases ***
 Example 1
     [Documentation]    First line\n    Second line in    multiple parts
     No Operation

 Example 2
     [Documentation]   First line
     ...               Second line in    multiple parts
     No Operation

 Example 3
     [Documentation]    First line\n
     ...                Second line in\
     ...                multiple parts
     No Operation

Documentation in test libraries ¶

With library documentations normal newlines are enough, and for example the following keyword documentation would create same end result as the test suite documentation in the previous section.

def example_keyword():
    """First line.

    Second paragraph, this time
    with multiple lines.
    """
    pass

Paragraphs ¶

Starting from Robot Framework 2.7.2, all regular text in the formatted HTML documentation is represented as paragraphs. In practice, lines separated by a single newline will be combined in a paragraph regardless whether the newline is added manually or automatically. Multiple paragraphs can be separated with an empty line (i.e. two newlines) and also tables, lists, and other specially formatted blocks discussed in subsequent sections end a paragraph.

For example, the following test suite or resource file documentation:

*** Settings ***
Documentation
...    First paragraph has only one line.
...
...    Second paragraph, this time created
...    with multiple lines.

will be formatted in HTML as:

First paragraph has only one line.

Second paragraph, this time created with multiple lines.

注釈

Prior to 2.7.2 handling paragraphs was inconsistent. In documentation generated with Libdoc_ lines were combined to paragraphs but in documentations shown in log and report they were not.

Inline styles ¶

The documentation syntax supports inline styles bold, italic and code. Bold text can be created by having an asterisk before and after the selected word or words, for example *this is bold*. Italic style works similarly, but the special character to use is an underscore, for example, _italic_. It is also possible to have bold italic with the syntax _*bold italic*_.

The code style is created using double backticks like ``code``. The result is monospaced text with light gray background. Support for code style is new in Robot Framework 2.8.6.

Asterisks, underscores or double backticks alone, or in the middle of a word, do not start formatting, but punctuation characters before or after them are allowed. When multiple lines form a paragraph, all inline styles can span over multiple lines.

Inline style examples
Unformatted	Formatted
bold	bold
_italic_	italic
_bold italic_	bold italic
``code``	`code`
bold, then _italic_ and finally ``some code``	bold, then italic and finally `some code`
This is bold\n on multiple\n lines.	This is bold on multiple lines.

URLs ¶

All strings that look like URLs are automatically converted into clickable links. Additionally, URLs that end with extension .jpg, .jpeg, .png, .gif or .bmp (case-insensitive) will automatically create images. For example, URLs like http://example.com are turned into links, and http:///host/image.jpg and file:///path/chart.png into images.

The automatic conversion of URLs to links is applied to all the data in logs and reports, but creating images is done only for test suite, test case and keyword documentation, and for test suite metadata.

Custom links and images ¶

Starting from Robot Framework 2.7, it is possible to create custom links and embed images using special syntax [link|content]. This creates a link or image depending are link and content images. They are considered images if they have the same image extensions that are special with URLs. The surrounding square brackets and the pipe character between the parts are mandatory in all cases.

Link with text content ¶

If neither link nor content is an image, the end result is a normal link where link is the link target and content the visible text:

[file.html|this file] -> <a href="file.html">this file</a>
[http://host|that host] -> <a href="http://host">that host</a>

Link with image content ¶

If content is an image, you get a link where the link content is an image. Link target is created by link and it can be either text or image:

[robot.html|robot.png] -> <a href="robot.html"><img src="robot.png"></a>
[image.jpg|thumb.jpg] -> <a href="image.jpg"><img src="thumb.jpg"></a>

Image with title text ¶

If link is an image but content is not, the syntax creates an image where the content is the title text shown when mouse is over the image:

[robot.jpeg|Robot rocks!] -> <img src="robot.jpeg" title="Robot rocks!">

Section titles ¶

If documentation gets longer, it is often a good idea to split it into sections. Starting from Robot Framework 2.7.5, it is possible to separate sections with titles using syntax = My Title =, where the number of equal signs denotes the level of the title:

= First section =

== Subsection ==

Some text.

== Second subsection ==

More text.

= Second section =

You probably got the idea.

Notice that only three title levels are supported and that spaces between equal signs and the title text are mandatory.

Tables ¶

Tables are created using pipe characters with spaces around them as column separators and newlines as row separators. Header cells can be created by surrounding the cell content with equal signs and optional spaces like = Header = or =Header=. Tables cells can also contain links and formatting such as bold and italic:

| =A= |  =B=  | = C =  |
| _1_ | Hello | world! |
| _2_ | Hi    |

The created table always has a thin border and normal text is left-aligned. Text in header cells is bold and centered. Empty cells are automatically added to make rows equally long. For example, the above example would be formatted like this in HTML:

A	B	C
1	Hello	world
2	Hi

注釈

Support for table headers is a new feature in Robot Framework 2.8.2.

Lists ¶

Lists are created by starting a line with a hyphen and space ('- '). List items can be split into multiple lines by indenting continuing lines with one or more spaces. A line that does not start with '- ' and is not indented ends the list:

Example:
- a list item
- second list item
  is continued

This is outside the list.

The above documentation is formatted like this in HTML:

Example:

a list item
second list item is continued

This is outside the list.

注釈

Support for formatting lists was added in 2.7.2. Prior to that, the same syntax prevented Libdoc_ from combining lines to paragraphs, so the end result was similar. Support for splitting list items into multiple lines was added in 2.7.4.

Preformatted text ¶

Starting from Robot Framework 2.7, it is possible to embed blocks of preformatted text in the documentation. Preformatted block is created by starting lines with '| ', one space being mandatory after the pipe character except on otherwise empty lines. The starting '| ' sequence will be removed from the resulting HTML, but all other whitespace is preserved.

In the following documentation, the two middle lines form a preformatted block when converted to HTML:

Doc before block:
| inside block
|    some   additional whitespace
After block.

The above documentation is formatted like this:

Doc before block:

inside block
  some   additional whitespace

After block.

When documenting suites, tests or keywords in Robot Framework test data, having multiple spaces requires escaping with a backslash to `prevent ignoring spaces`_. The example above would thus be written like this:

Doc before block:
| inside block
| \ \ \ some \ \ additional whitespace
After block.

Horizontal ruler ¶

Horizontal rulers (the <hr> tag) make it possible to separate larger sections from each others, and they can be created by having three or more hyphens alone on a line:

Some text here.

---

More text...