From f26e7d74d285fc8bc94c7a70fa7b41d5fac205c2 Mon Sep 17 00:00:00 2001 From: Tatu Aalto Date: Sun, 1 Nov 2026 19:41:28 +0200 Subject: [PATCH] docs: fix keyword and type documentation rendering in Libdoc Record Keyword, Record Keywords and Record Selector arrived in #5413 after #5266 converted the argument tables, so they kept the old table and had no per-argument documentation in Robot Framework 7.5 Libdoc. Single backticks on plain values made Libdoc look for a link target. Without one they rendered as names, not code, and RecordHar's `path` linked to the unrelated Path type. Use double backticks instead. AutoClosingLevel and PlaywrightLogTypes are used only by __init__, and Libdoc builds type link targets from keywords, so they now link to the type anchors explicitly. Co-Authored-By: Claude Opus 5.5 --- Browser/browser.py | 14 +++++----- Browser/keywords/credential.py | 2 +- Browser/keywords/recorder.py | 48 ++++++++++++++++++++++++++-------- Browser/utils/data_types.py | 24 ++++++++--------- 4 files changed, 56 insertions(+), 32 deletions(-) diff --git a/Browser/browser.py b/Browser/browser.py index 61e670f3c..f8a061f31 100755 --- a/Browser/browser.py +++ b/Browser/browser.py @@ -381,10 +381,8 @@ class Browser(DynamicCore): Browser library running on the same machine, instead of each one starting its own. This can speed up parallel runs. Start it from the directory where the Browser package is installed with - ``` - PLAYWRIGHT_BROWSERS_PATH=0 node Browser/wrapper/index.js HOST PORT - ``` - , for example ``... index.js 127.0.0.1 12345``. Both arguments are required: the + ``PLAYWRIGHT_BROWSERS_PATH=0 node Browser/wrapper/index.js HOST PORT``, + for example ``... index.js 127.0.0.1 12345``. Both arguments are required: the script reads the host first and exits with ``No port defined`` if only one is given. Point runs at it with the ``playwright_process_port`` import parameter or the @@ -499,19 +497,19 @@ def __init__( # noqa: PLR0915 *Arguments:* - ``_``: Positional arguments are ignored. All arguments must be passed as named arguments. - ``auto_closing_level``: Configure context and page automatic closing. - Default is ``TEST``, for more details, see `AutoClosingLevel` + Default is ``TEST``, for more details, see [#type-AutoClosingLevel|AutoClosingLevel] - ``auto_delete_passed_tracing``: If ``auto_closing_level`` is set to ``SUITE`` or ``TEST`` and ``tracing`` of `New Context` active, traces of passed tests or suites, depending on the context scope, will not be saved. Also temp files will all be deleted after the whole execution ends. - ``enable_playwright_debug``: Enable low level debug information from the playwright to playwright-log.txt file. For more details, see - `PlaywrightLogTypes`. + [#type-PlaywrightLogTypes|PlaywrightLogTypes]. - ``enable_presenter_mode``: Automatic highlights the interacted components, slowMo and a small pause at the end. Can be enabled by giving True or can be customized by giving a dictionary: ``{"duration": "2 seconds", - "width": "2px", "style": "dotted", "color": "blue"}`` Where `duration` is - time format in Robot Framework format, defaults to 2 seconds. `width` is + "width": "2px", "style": "dotted", "color": "blue"}`` Where ``duration`` is + time format in Robot Framework format, defaults to 2 seconds. ``width`` is width of the marker in pixels, defaults the ``2px``. ``style`` is the style of border, defaults to ``dotted``. ``color`` is the color of the marker, defaults to ``blue``. By default, the call banner keyword is also enabled diff --git a/Browser/keywords/credential.py b/Browser/keywords/credential.py index 22060ea91..8a6403289 100644 --- a/Browser/keywords/credential.py +++ b/Browser/keywords/credential.py @@ -165,7 +165,7 @@ def get_credential( type, so that their values are not shown in the Robot Framework log. The values themselves are available in the ``value`` attribute. Note that the node side of the library might write the whole credential, including the private key, as plain text to the - playwright-log.txt file. See `PlaywrightLogTypes` for how to control that file. + playwright-log.txt file. See [#type-PlaywrightLogTypes|PlaywrightLogTypes] for how to control that file. See `Install Credential` for more information about how to use this keyword. diff --git a/Browser/keywords/recorder.py b/Browser/keywords/recorder.py index 3832d2c97..43020dcb1 100644 --- a/Browser/keywords/recorder.py +++ b/Browser/keywords/recorder.py @@ -180,10 +180,22 @@ def record_keyword( pages are closed, or on an error. The keyword being recorded is saved unless it has no Keyword Calls. - | =Arguments= | =Description= | - | ``name`` | Name of the User Keyword to create. It must not exist in ``file`` and must not shadow any keyword the running suite can call. | - | ``file`` | Target ``.robot`` or ``.resource`` file. Defaults to ``${SUITE_SOURCE}``, the file of the running suite; in a suite initialisation file that is its ``__init__.robot``, and a keyword recorded there can only be used in that file. A relative path is resolved against the current working directory, not against the suite; use ``${CURDIR}`` for a file next to the suite. The folder must exist and an existing file must be writable; both are checked before recording starts. With ``${None}`` nothing is written; the keyword is logged to the console and to the log at INFO level instead. | - | ``idle_timeout`` | Ends the recording after this long without an Action or toolbar command. Must be greater than zero. Default: 5 minutes, so a forgotten recording does not block the run for good. ``${None}`` waits without limit. | + *Arguments:* + - ``name``: Name of the User Keyword to create. It must not exist in + ``file`` and must not shadow any keyword the running suite can call. + - ``file``: Target ``.robot`` or ``.resource`` file. Defaults to + ``${SUITE_SOURCE}``, the file of the running suite; in a suite + initialisation file that is its ``__init__.robot``, and a keyword recorded + there can only be used in that file. A relative path is resolved against the + current working directory, not against the suite; use ``${CURDIR}`` for a + file next to the suite. The folder must exist and an existing file must be + writable; both are checked before recording starts. With ``${None}`` nothing + is written; the keyword is logged to the console and to the log at INFO + level instead. + - ``idle_timeout``: Ends the recording after this long without an Action or + toolbar command. Must be greater than zero. Default: 5 minutes, so a + forgotten recording does not block the run for good. ``${None}`` waits + without limit. Returns the text of the recorded keyword, including the ``*** Keywords ***`` header. If a recorded keyword cannot be written - the file became read-only, the disk is @@ -294,9 +306,20 @@ def record_keywords( pages are closed, or on an error. The keyword being recorded is saved unless it has no Keyword Calls. - | =Arguments= | =Description= | - | ``file`` | Target ``.robot`` or ``.resource`` file. Defaults to ``${SUITE_SOURCE}``, the file of the running suite; in a suite initialisation file that is its ``__init__.robot``, and a keyword recorded there can only be used in that file. A relative path is resolved against the current working directory, not against the suite; use ``${CURDIR}`` for a file next to the suite. The folder must exist and an existing file must be writable; both are checked before recording starts. With ``${None}`` nothing is written; the keywords are logged to the console and to the log at INFO level instead. | - | ``idle_timeout`` | Ends the recording after this long without an Action or toolbar command. Must be greater than zero. Default: 5 minutes, so a forgotten recording does not block the run for good. ``${None}`` waits without limit. | + *Arguments:* + - ``file``: Target ``.robot`` or ``.resource`` file. Defaults to + ``${SUITE_SOURCE}``, the file of the running suite; in a suite + initialisation file that is its ``__init__.robot``, and a keyword recorded + there can only be used in that file. A relative path is resolved against the + current working directory, not against the suite; use ``${CURDIR}`` for a + file next to the suite. The folder must exist and an existing file must be + writable; both are checked before recording starts. With ``${None}`` nothing + is written; the keywords are logged to the console and to the log at INFO + level instead. + - ``idle_timeout``: Ends the recording after this long without an Action or + toolbar command. Must be greater than zero. Default: 5 minutes, so a + forgotten recording does not block the run for good. ``${None}`` waits + without limit. Returns the text of all keywords recorded in the session, under one ``*** Keywords ***`` header. @@ -383,10 +406,13 @@ def record_selector( - *✕* in the header, or Escape in the toolbar: cancels, and the keyword fails. - Minimized, the header offers *Reselect* and *Use* once an element is picked. - | =Arguments= | =Description= | - | ``label`` | Shown in the toolbar header, to say which element to pick. | - | ``generator`` | The generator the toolbar starts with; the toolbar can switch it. ``playwright`` (default) or ``css``. | - | ``idle_timeout`` | Fails the keyword after this long without a pick or toolbar command. Must be greater than zero. Default: 5 minutes. ``${None}`` waits without limit. | + *Arguments:* + - ``label``: Shown in the toolbar header, to say which element to pick. + - ``generator``: The generator the toolbar starts with; the toolbar can + switch it. ``playwright`` (default) or ``css``. + - ``idle_timeout``: Fails the keyword after this long without a pick or + toolbar command. Must be greater than zero. Default: 5 minutes. ``${None}`` + waits without limit. Fails in a headless browser, while a `Record Keyword` or `Record Keywords` session runs in the browser context, when the page is closed, on cancel and when the diff --git a/Browser/utils/data_types.py b/Browser/utils/data_types.py index 43f052fdc..0ae7237d8 100644 --- a/Browser/utils/data_types.py +++ b/Browser/utils/data_types.py @@ -162,7 +162,7 @@ class NotSet(Enum): This is used to differentiate between a value that is set to None and a value that is not set at all. Example `ForcedColors` has an options active, none and null. If user does not not want to give any of - the `ForcedColors` options, user can use `not_set` value. Then keyword + the `ForcedColors` options, user can use ``not_set`` value. Then keyword will not define `ForcedColors` option at all when underlying Playwright method(s) is called. """ @@ -771,10 +771,10 @@ class RecordHar(TypedDict, total=False): If not specified, the HAR is not recorded. Make sure to await context to close for the [http://www.softwareishard.com/blog/har-12-spec/|HAR] to be saved. - `omitContent`: Optional setting to control whether to omit request content + ``omitContent``: Optional setting to control whether to omit request content from the HAR. Default is False - `path`: Path on the filesystem to write the HAR file to. A relative path is + ``path``: Path on the filesystem to write the HAR file to. A relative path is relative to the output directory. Example: @@ -1515,7 +1515,7 @@ class PageLoadStates(Enum): class ReduceMotion(Enum): - """Emulates `prefers-reduced-motion` media feature, supported values are `reduce`, `no-preference`.""" + """Emulates ``prefers-reduced-motion`` media feature, supported values are ``reduce``, ``no-preference``.""" reduce = auto() no_preference = auto() @@ -1637,8 +1637,8 @@ class PlaywrightLogTypes(Enum): ``disabled``: playwright-log.txt is not created at all. All node side logging is lost. ``library``: Default, only logging from Browser library node side is written to the playwright-log.txt file. ``playwright``: Also includes Playwright log messages to the playwright-log.txt file. - ``false``: Same as `library` and for backwards compatability. - ``true``: Same as `playwright` and for backwards compatibility. + ``false``: Same as ``library`` and for backwards compatability. + ``true``: Same as ``playwright`` and for backwards compatibility. """ disabled = auto() @@ -1769,10 +1769,10 @@ class ClockType(Enum): ``fixed``: Sets the fixed time for Date.now() and new Date(). ``system``: Is only recommended for advanced use cases. ``install``: initializes the clock and allows you to: - `pause_at`: Pauses the time at a specific time. - `fast_forward`: Fast forwards the time. - `run_for`: Runs the time for a specific duration. - `resume`: Resumes the time. + ``pause_at``: Pauses the time at a specific time. + ``fast_forward``: Fast forwards the time. + ``run_for``: Runs the time for a specific duration. + ``resume``: Resumes the time. """ fixed = auto() @@ -1852,9 +1852,9 @@ class TracingGroupMode(Enum): class TextType(Enum): """Defines which Playwright method is used to get the text of an element. - ``allInnerTexts``: Returns a list of `node.innerText` values for all matching nodes. + ``allInnerTexts``: Returns a list of ``node.innerText`` values for all matching nodes. - ``allTextContents``: Returns a list of `node.textContent` values for all matching nodes. + ``allTextContents``: Returns a list of ``node.textContent`` values for all matching nodes. ``innerText``: Returns the element node.innerText value, which represents the rendered text content of a node and its descendants.