robotframework-testdoc 0.6.4

A CLI Tool to generate a Test Documentation for your RobotFramework Test Scripts.

robotframework-testdoc

The new tool to generate test documentation pages for your Robot Framework project.

GitHub Project

Visit the project at GitHub - robotframework-testdoc

Documentation

Visit the official documentation for more details: Documentation - robotframework-testdoc

VS Code Extension

Generate test documentation directly from the VS Code Explorer — no terminal required.
Download the latest .vsix from GitHub Releases and install it locally.

code --install-extension testdoc-vscode-<version>.vsix

See the VS Code Extension documentation for details.

Statistics

Installation

Install the tool using the following command:

pip install robotframework-testdoc

Usage

Basic Usage

testdoc suite_directory output.html
# or
testdoc suite_file output.html

Extended Usage

testdoc [OPTIONS] suite_directory output.html

[!TIP] Included Help: Visit the CLI Documentation for further arguments & details.

Output Formats

By default testdoc generates an HTML file. Use -f / --output-format to choose a different format:

# HTML (default)
testdoc tests/ TestDocumentation.html

# JSON — machine-readable suite tree
testdoc -f json tests/ TestDocumentation.json

Available values: html (default), json.

Plugin Usage

You can use the testdoc tool also as plugin integration.
You have two option to use it this way:

1. You can write your own HTML page as jinja2 template, add this HTML template as CLI argument while generating the docs and you will get your own HTML style as documentation page.
2. You can use the mkdocs integration to define your own mkdcs template as CLI argument and the testdoc tool will internally take care of the mkdocs page generation.

For further details about the usage, please read the official documentation.

Use customized Jinja2 HTML Template

Use internal Mkdocs Template

Use customized Mkdocs Template

Examples

Visit the official documentation to find some Examples.

External Configuration File

The idea of the external configuration file is, having a central place for passing the known CMD arguments via file instead of CMD parameters.
This will keep your CMD line call simple & clean.

For using this config file, just call the following command:

# Generate docu with options defined in TOML file
testdoc -c path/to/config.toml tests/ TestDocumentation.html

pyproject.toml vs. custom toml file

Using the pyproject requires to define the testdoc sections with the prefix tool.
Example section start: [tool.testdoc]

Using your own custom toml-file, does not require you to use the prefix. Here, you can just use [testdoc] as section header.

Example Configuration File

[tool.testdoc]
title = "New title of HTML document"
name = "New name of root suite element"
doc = "New doc text of root suite element"
sourceprefix = "gitlab::https://gitlab.com/myrepo/repo_path"
include = ["TagA", "TagB"]
exclude = ["TagC"]
verbose_mode = false

[tool.testdoc.metadata]
Author = "Your-Name"
Version = "1.0.0"
Source = "AnySourceAsMetaData"

Contribution & Development

See Development.md for more information about contributing & developing this library.