Leveraging Robot Framework's Documentation Support

Robot_Framework_Generate_Documentation_Tutorial.md

Leveraging Robot Framework's Documentation Support

Introduction

This is a short tutorial on how to leverage Robot Framework's built-in support for documentation. This documentation can be embedded in test suites, libraries, and other resource files. The markup is fairly simple, and most closely resembles AsciiDoc syntax.

Official Documentation

The official documentation explains the use of the Library documentation tool (Libdoc), its correspondent for Test data documentation (Testdoc), as well as the Documentation formatting syntax. Please use these references as the official word on how to format and generate Robot Framework testing documentation.

Briefly, to generate Library/Resource documentation:

libdoc [options] library.py library_docs.html
libdoc [options] my_resources.resource my_resources_docs.html

As mentioned, see official documentation for the list of possible options. The source and destination files should be adjusted to your project, but adding .html will let libdoc know that's the format you desire for the output file (other file types include xml, json, or libspec).

To generate Test Suite documentation:

python -m robot.testdoc [options] test_source_path_or_file output_file.html

As above, see the official documentation for the list of possible options. The source and destination files should be adjusted to your project.

Documentation Blocks

We'll first cover how to indicate where documentation blocks are indicated, and how to specify multiple lines.

Suite-level Documentation

Suite-level documentation (which could, for example, explain the purpose of the suite, how to run it, etc.) is found under the *** Settings *** section at the top of the suite file. For this level of documentation, you should start a line with the word Documentation, followed by the de facto number of spaces (4 - as is true of Python) and begin your documentation. To avoid overly-long lines, you should continue your documentation paragraph by adding a newline, starting the next line with three 'dots' (...), and adding enough spaces to align the next line with the beginning of the documentation. Here's an example:

*** Settings ***
Documentation    This is the start of our documentation. I plan on writing a lot,
...              so I will have more than one line. However, when rendered, this
...              entire block will be one paragraph, without the newlines within it.

To start a new paragraph, you'll need to add a blank line in between or add an escaped newline (\n) as part of the documentation. Here are examples of each below:

*** Settings ***
Documentation    This is the start of our documentation. This is the first
...              paragraph.
...
...              This is the second paragraph. Because of the blank line above,
...              this chunk will be rendered as a separate paragraph from the
...              first.
...
...              This is the third paragraph.\n
...              This is the fourth paragraph, due to the preceding line's 
...              escaped newline.

Test-level Documentation

Besides the suite-level documentation, you can also have documentation for each test case. Below you'll find an example of how to create documentation by adding the metatag [Documentation] as part of the indented block within a test case. Here's some examples:

*** Test Cases ***
 Test Case 1
     [Documentation]   First line
     ...               Second line
     No Operation

 Test Case 2
     [Documentation]    First line\n
     ...                Second line in
     ...                multiple parts
     No Operation

Inline Styling

Inline styling includes bold, italic, and code. Here's a table to show how they are indicated and rendered:

Markup	Rendered
_italic_	italic
*bold*	bold
_*bold italic*_	bold italic
``monospace``	monospace

Hyperlinks

If you have a bare hyperlink within documentation, it will be rendered as such. Thus, https://www.google.com will be rendered as a hyperlink: https://www.google.com

If, however, you want to create an anchored link text (that is, a string that itself is a hyperlink), the hyperlink will need to be in this format:

[HYPERLINK HERE|The link text here]

That is, opening square bracket ([), followed by the actual URL, followed by a pipe (|), followed by the link description text and then a closing square bracket (]). Thus, our Google example above would look something like this:

[https://www.google.com|Google's main landing page]

...and would render like this:

Google's main landing page

Keyword Links

Unlike Markdown, which uses a single backtick on each side of a monospace block, Robot Framework expects 2 backticks on either side (as seen in the table above) for monospace/code blocks. However, a single backtick on either side of a word indicates to the RF documentation tools that it should link to a keyword defined somewhere within the page. For example, if you have a keyword called Data Prep Case and want to link to it, you would embed the link as follows:

*** Keywords ***
 A Keyword
     [Documentation]   *Note*: you must run the `Data Prep Case` first.
     No Operation

 Data Prep Case
     [Documentation]    This is the keyword that makes sure the data
     ...                for testing is populated in the database.
     No Operation

Lists

Lists are created with each item on a new line with a dash at the beginning. Thus, the following:

*My List*
- First item
- Second item
- Third item
  with longer text

would render as:

My List

• First item
• Second item
• Third item with longer text

Section Titles

You can designate headings/section titles within a larger body of documentation that roughly correspond to HTML H1, H2, and H3. Each section level uses 1, 2, or 3 equals signs to either side of the heading as markup. The markup is as follows:

= First section =

Something here that you want to say.

== Subsection within First Section ==

More text.

== Second subsection ==

More text.

= Second section =

More stuff.

== Second Section Subheading ==

Things here.

=== Sub-sub-heading ===

Yes, this is like H3.

This would render similar to the following:

---

First section

Something here that you want to say.

Subsection within First Section

More text.

Second subsection

More text.

Second section

More stuff.

Second Section Subheading

Things here.

Sub-sub-heading

Yes, this is like H3.

---

Tables

Tables are simple pipe-delimited blocks. The first line is not rendered differently, so you will need to use either the bold formatting or Heading markup to make it stand out.

Here's a table without any additional formatting:

| *First Col*  | *Second Col* | *Third Col*  |
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |

This would render similarly to the following:

First Col	Second Col	Third Col
Row 1, Col 1	Row 1, Col 2	Row 1, Col 3
Row 2, Col 1	Row 2, Col 2	Row 2, Col 3

Conclusion

This is a mere overview. Readers are encouraged to read the full documentation, under the heading 6.3 Documentation formatting.