Skip to content

Robot Framework Manual

This site is a playground for testing Material for Mkdocs features to be used with the Robot Framework Manual that is going to replace the old Robot Framework User Guide. To see the source code, click the edit button on right or go to the pekkaklarck/mkdocs-experiments repository.

Test or task?

Use the toggle in the header to choose the mode and the following two chapters are changed based on that. The first chapter uses testtask markup that's rendered like test or task based on the mode. The second chapter and the associated example are replaced altogether.

Should we use testtask? TestTasks we shall use!

This paragraph is relevant only when doing test automation. We love bugs! 

1
2
3
*** Test Cases ****** Tasks ***
Testing example
    Log    Hello, testers!

This is a paragraph only for the RPA users. We love processes! 

1
2
3
*** Tasks ***
RPA example
    Log    Hello, process automators!

Everyone needs this paragraph and the following example, but the example is adapted based on the mode.

1
2
3
4
*** Test Cases ****** Tasks ***
Example for all
    [Documentation]    Only the header changes!
    Log    Hello, world!

Emojis and icons

Lot of emojis and icons are supported:

Being able to add custom icons is handy, but because Simple Icons already has , having also custom may not be useful.

Code snippets

Here's a simple Robot Framework example to get us started! 🚀

1
2
3
*** Test Cases ****** Tasks ***
Example
    Log    Hello, world!    # (1)!
  1. Code annotations work also with 🤖 examples! 🤯

Did you see the plus sign above? It's a code annotation. Click it!

And here's another example using :

1
2
def example():
    print('Hello, world!')

Above examples used fenced code blocks. Here's another Python example using a simple indented code block:

1
2
def example():
    print('Hello, world!')    # (1)!
  1. Python is configured to be the default language for intended code blocks.

Standard Markdown syntax:

Features provided by the autorefs plugin:

Features provided by the MagicLink plugin:

Below we have an image. It uses link-like syntax as well. It also has a custom anchor.

Logo

Glossary

Keyword is a term in our glossary. Term lookup is case-insensitive and takes plural forms into account, so we can refer to a term specified as Library keyword like library keywords.

Glossary functionality is provided by the mkdocs-ezglossary plugin.

Tabs

Tabs can be really useful for us!

They are provided by the pymdownx.tabbed plugin.

Markdown content.

  • list item a
  • list item b
  • 🎉
1
2
def greet(name):
    print(f'Hello, {name}!')

1
2
3
*** Test Cases ****** Tasks ***
Example
    Greet    Robot

Admonitions

Note

All this content is only for experimenting purposes.

1
a = 1 + 2    # superfences!

Tip

"Normal" admonitions are provided by the standard admonition plugin.

Collapsed!

Some initially hidden content here.

Success

Collapsible admonitions can be initially expendad. They are provided by the pymdownx.details plugin.

Versioning

Versioning has been set up using mike as Material for Mkdocs documentation recommends and automated using GitHub Actions.

How it works

This is how versioning works for users viewing the docs and for developers writing them:

  • When a normal commit is pushed, documentation for the dev version is generated automatically. New documentation overrides the existing dev docs.
  • When a new stable release tag in format like v0.1 or v2.0.1 is pushed, documentation is generated for that release.
  • Release documentation versions use only two components like 2.0. If new releases in same series are created, they override existing documentation for that release. For example, if there is first release 2.0 (generated from tag v2.0) and then 2.0.1 is released (from tag v2.0.1), the shown 2.0 docs contain documentation for version 2.0.1.
  • Separate documentation is not generated for pre-releases like 2.1rc1. It is possible to view the dev docs instead.
  • latest version is an alias that always points to the docs of the latest release.
  • Opening the documentation root automatically redirects to latest.
  • It is possible to switch between versions using the widget in the page header.
  • Viewing any other documentation version than latest causes a warning to be shown.

Setting it up

This is how versioning has been set up:

  • mike is listed in requirements.txt.
  • Possible old docs from gh-pages root should be removed or moved to a dedicated directory. Running mike delete --all --push nukes everything, but you need to make sure your local gh-pages branch is in sync with the origin (and that there is nothing valuable that should not be removed).
  • mkdocs.yml configuration:
  • Versioning is configured under extra.
  • mike itself is configured under plugins.
  • site_url should, for some reason, contain a trailing /.
  • theme/custom_dir sets up the directory containing template for outdated version warning. That directory is also listed under watch.
  • overrides/main.html contains the aforementioned outdated version warning.
  • .github/workflows/dev-docs.yml contains configuration for generating dev docs.
  • .github/workflows/release-docs.yml contains configuration for generating release docs.
  • The following commands needs to be run once to configure the default version.

    mike set-default --push --allow-undefined latest

  • To get social cards working when someone refers to the documentation root, copy related og:xxx (and twitter:xxx) meta tags from latest/index.html to /index.html. See this project's index.html for an example.

Warning

If workflows for generating dev and release docs are run at the same time, they may conflict when they try to push changes to gh-pages. They should be configured to wait for each others, but that didn't seem to be straightforward. Until that's done, care must be taken not to push release tags until dev doc generation has finished.