Principle:MarketSquare Robotframework browser Plugin Documentation Generation

Plugin Documentation Generation

Overview

The robotframework-browser library provides comprehensive documentation generation that encompasses both built-in keywords and plugin keywords. Two complementary documentation mechanisms exist: HTML keyword documentation via Robot Framework's libdoc tool, and type stub generation for IDE autocompletion via the gen_stub.py script. When plugins are involved, special syntax ensures their keywords appear in the generated documentation.

Core Concept: Inclusive Documentation

A test library's documentation is only useful if it reflects the complete set of available keywords. Since plugins add keywords at import time, the documentation generation process must instantiate the library with the desired plugins to capture their keywords.

This creates a documentation challenge unique to dynamic libraries: the keyword set depends on how the library is imported. The robotframework-browser library addresses this by supporting a ::plugins= syntax in documentation generation commands.

HTML Keyword Documentation with libdoc

Robot Framework's libdoc tool generates HTML documentation pages listing all keywords, their arguments, types, tags, and docstrings. For the Browser library, this is invoked through the docs task in tasks.py.

Basic Documentation Generation

from robot.libdoc import libdoc

libdoc("Browser", "docs/Browser.html")

This generates documentation for the Browser library without any plugins. Only built-in keywords appear.

Documentation with Plugins

To include plugin keywords in the documentation, use the ::plugins= syntax:

from robot.libdoc import libdoc

libdoc("Browser::plugins=path/to/MyPlugin.py", "docs/Browser.html")

This instructs libdoc to pass the plugins argument when instantiating the Browser library. The library then loads the specified plugins, and their keywords are included in the generated documentation.

The :: syntax is Robot Framework's mechanism for passing constructor arguments to a library during documentation generation. Multiple arguments can be chained:

libdoc(
    "Browser::plugins=path/to/Plugin.py::timeout=30s",
    "docs/Browser.html"
)

Plugin Keywords in Documentation

When plugins are included, their keywords appear alongside built-in keywords in the documentation. Plugin keywords are distinguished by:

The Plugin tag -- automatically added by Browser.get_keyword_tags()
Any additional tags the plugin author specified via @keyword(tags=...)
The keyword's docstring, which comes from the Python method's docstring

Type Stub Generation for IDE Support

The gen_stub.py script generates Python type stub files (.pyi) that enable IDE autocompletion and type checking. These stubs allow tools like PyCharm, VS Code (Pylance), and mypy to understand the Browser library's keyword signatures.

How gen_stub.py Works

The stub generation process follows these steps:

Instantiate the Browser library to discover all keywords and their method names
Read mypy stub files from mypy_stub/Browser/keywords/*.pyi
Extract keyword method signatures by matching method names from step 1
Combine signatures into a single Browser/browser.pyi file with proper imports

# From Browser/gen_stub.py
BR: Browser.Browser = Browser.Browser()
KW_METHOD_NAMES = [kw.__name__ for kw in BR.keywords.values()]

The script creates a Browser instance (without plugins) to discover the complete list of built-in keyword method names. It then searches through hand-written stub files for matching method signatures.

parse_kw_module_lines

def parse_kw_module_lines(lines: list[str]):
    for line in lines:
        for method_name in KW_METHOD_NAMES:
            if f"def {method_name}(" in line and method_name not in ADDED_KW:
                ADDED_KW.append(method_name)
                yield line

This function scans each line of a stub file, looking for method definitions that match known keyword names. It yields matching lines and tracks which keywords have already been added to avoid duplicates.

parse_kw_stubs

def parse_kw_stubs():
    for file in Path("mypy_stub/Browser/keywords").rglob("*.pyi"):
        with file.open("r", encoding="utf-8") as f:
            lines = f.readlines()
            yield from parse_kw_module_lines(lines)

This function iterates over all .pyi files in the mypy_stub/Browser/keywords/ directory and extracts keyword method signatures.

The Documentation Pipeline

The complete documentation pipeline for the Browser library includes:

Step	Tool	Input	Output
1. Stub generation	`Browser/gen_stub.py`	`mypy_stub/Browser/keywords/*.pyi` + `mypy_stub/Browser/browser.pyi`	`Browser/browser.pyi`
2. HTML docs	`robot.libdoc.libdoc()`	Browser library (with optional plugins)	`docs/Browser.html`
3. Version docs	`tasks.py:docs()`	`docs/Browser.html`	`docs/versions/Browser-{version}.html`

Plugin Documentation Best Practices

Writing Good Docstrings

Since keyword docstrings become the keyword documentation, plugin authors should write clear, descriptive docstrings:

@keyword
def new_plugin_cookie_keyword(self) -> dict:
    """Uses grpc to directly call node side function.

    Returns a dictionary with 'name' and 'value' keys
    from the first cookie in the current context.

    Raises AssertionError if more than one cookie exists.
    """
    ...

Using Tags for Organization

Plugin keywords should use meaningful tags to help users discover them in documentation:

@keyword(tags=("Cookie", "Network"))
def get_custom_cookies(self) -> list:
    """Returns cookies with custom filtering logic."""
    ...

Type Annotations for Documentation

Type annotations on keyword parameters appear in the generated documentation, helping users understand expected argument types:

@keyword
def scroll_element(self, selector: str, x: int = 0, y: int = 100) -> int:
    """Scrolls an element by the specified pixel amounts."""
    ...

Generating Documentation for Plugin Users

Users who consume plugins can generate documentation that includes those plugins:

# From command line using Robot Framework's libdoc
python -m robot.libdoc "Browser::plugins=path/to/MyPlugin.py" docs/MyProject.html

# In Robot Framework settings, for runtime reference
Library    Browser    plugins=${CURDIR}/MyPlugin.py

Domains

Implemented By

Implementation:MarketSquare_Robotframework_browser_Libdoc_Gen_Stub

MarketSquare_Robotframework_browser_Libdoc_Gen_Stub -- Implementation details of gen_stub.py and libdoc integration
MarketSquare_Robotframework_browser_Plugin_Architecture -- The plugin system whose keywords are documented
MarketSquare_Robotframework_browser_Keyword_Decorator_Pattern -- How keyword docstrings and tags are defined

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment