diff --git a/website/docs/chapter-02/01_suitefile.md b/website/docs/chapter-02/01_suitefile.md index 065bae6..8b535c6 100644 --- a/website/docs/chapter-02/01_suitefile.md +++ b/website/docs/chapter-02/01_suitefile.md @@ -128,7 +128,7 @@ It allows you to import keywords from external libraries (`Library`) or resource In this section, the suite name, that is normally derived from the file name, can be redefined with the `Name` setting and its documentation can be defined with the `Documentation` setting. -Additional suite metadata can be defined by multiple `Metadata` entries, which can contain key-value pairs that can be used to store additional information about the suite, like the author, the version, or related requirements of the suite. +Additional :term[suite metadata]{term="Suite Metadata"} can be defined by multiple `Metadata` entries, which can contain key-value pairs that can be used to store additional information about the suite, like the author, the version, or related requirements of the suite. This section can also define keywords called for execution flow control, such as `Suite Setup` and `Suite Teardown`, which are executed before and after the suite's tests run. See [4.1 Setups (Suite, Test|Task, Keyword)](chapter-04/01_setups.md) and [4.2 Teardowns (Suite, Test|Task, Keyword)](chapter-04/02_teardowns.md) for more information. @@ -142,10 +142,13 @@ Those settings are prefixed with either `Test` or `Task`, according to the type - `Test Timeout`/`Task Timeout` (locally `[Timeout]`) defines the maximum time a test|task is allowed to run before it is marked as failed. The local setting overrides the suite's default. -- `Test Tags`/`Task Tags` (locally `[Tags]`) define tags that are assigned to tests|tasks in the suite and can be used to filter tests|tasks for execution or for attributing information to the tests|tasks. The local setting appends or removes tags defined by the suite's default. See [4.4 Test|Task Tags and Filtering Execution](chapter-04/04_tags.md) for more information. +- `Test Tags`/`Task Tags` (locally `[Tags]`) define tags that are assigned to tests|tasks in the suite and can be used to group them, filter their execution, and create result statistics. The local setting appends or removes tags defined by the suite's default. See [4.4 Test|Task Tags and Filtering Execution](chapter-04/04_tags.md) for more information. - `Test Template`/`Task Template` (locally `[Template]`) defines a template keyword that defines the test|task body and is typically used for Data-Driven Testing where each test has the same keywords but different argument data. The local setting overrides the suite's default. +Individual tests|tasks can also define their own :term[test|task metadata]{term="Test Metadata"} using the `[Metadata]` setting with named key-value pairs such as an issue ID, author, or requirement reference. +Unlike tags, metadata is meant for descriptive information with explicit names and values and is not used for test|task selection. + Similar to test|task tags, also keyword tags can be defined in the `*** Settings ***` section with the `Keyword Tags` (locally `[Tags]`) setting, which can be used to set keyword tags to the keywords. The local setting appends or removes tags defined by the suite's default. @@ -188,7 +191,7 @@ Test cases and tasks are technically synonyms for each other. However, users have to choose one of the two modes of suite execution that Robot Framework offers. Each test case or task is structured using an indentation-based format. The first un-indented line specifies the name of the test|task, followed by indented lines containing **keyword calls** and their possible **arguments** and test|task-specific settings. -These optional settings like `[Setup]`, `[Teardown]`, and `[Timeout]` can be applied to individual test cases or tasks to control their behavior or provide additional details. +These optional settings like `[Setup]`, `[Teardown]`, `[Timeout]`, `[Tags]`, and `[Metadata]` can be applied to individual test cases or tasks to control their behavior or provide additional details. A suite file must contain either a `*** Test Cases ***` or a `*** Tasks ***` section, but not both. Resource files cannot contain either of them. @@ -232,4 +235,3 @@ All content in this section is ignored by Robot Framework and is not executed or - diff --git a/website/docs/chapter-02/05_keyword_interface.md b/website/docs/chapter-02/05_keyword_interface.md index 562e301..5c6ba48 100644 --- a/website/docs/chapter-02/05_keyword_interface.md +++ b/website/docs/chapter-02/05_keyword_interface.md @@ -1,4 +1,6 @@ +import NamedOnlyIcon from '@site/static/img/libdoc-icons/named-only.svg'; + # 2.5 Keyword Interface and Documentation ::::lo[Learning Objectives] @@ -14,9 +16,9 @@ Understand the structure of keyword interfaces and how to interpret keyword docu Library Keywords and User Keywords that are defined in a resource file should have a documentation text that describes what the keyword does and how it should be used. Robot Framework is capable of generating **Keyword Documentation** files that contain a library- or resource-documentation, all keywords, their argument interfaces, and their documentation texts. -This documentation file can be generated with the `libdoc` command and can be used to provide a reference for users who want to use the keywords. +This documentation can be generated with the `libdoc` command and can be used to provide a reference for users who want to use the keywords. -Basically all standard and external 3rd party libraries offer these Keyword Documentations as online available HTML pages. +Basically all standard and external 3rd party libraries offer these Keyword Documentations as online available pages. Robot Framework offers the Keyword Documentation of its Standard Libraries at https://robotframework.org/robotframework . @@ -44,6 +46,7 @@ Each library or resource documentation can contain the following information sec - **Return Type** (opt.): The type of the return value of the keyword. - (*) **Tags** (opt.): The tags that are assigned to the keyword to categorize keywords. - **Documentation** (opt.): The documentation text that describes what the keyword does and how it should be used. +- **Additional structured details in the documentation** (opt.): Depending on the library and Robot Framework version, the documentation may also contain formatted examples, more detailed argument descriptions, return value notes, and possible exception information. (*) Understanding keyword tags is not part of the syllabus. @@ -318,7 +321,7 @@ Recall what properties "Named-Only Arguments" have and how they are documented. All arguments that are defined after a :term[Variable Number of Positional Arguments] (`*varargs`) are :term[Named-Only Arguments]{term="Named-Only Argument"}. However it is also possible to create :term[Named-Only Arguments]{term="Named-Only Argument"} without a preceding :term[Variable Number of Positional Arguments]. -:term[Named-Only Arguments]{term="Named-Only Argument"} are marked with a "LABEL" sign `🏷` before the argument name in the keyword documentation. +:term[Named-Only Arguments]{term="Named-Only Argument"} are marked with a "LABEL" sign before the argument name in the keyword documentation. Those arguments can not be set positionally. All positional values would be consumed by the :term[Variable Number of Positional Arguments]. So they must be called by their name followed by an equal sign `=` and the value of the argument. @@ -475,5 +478,3 @@ Should Be Equal ${x} expected ignore_case=True formatter=repr ``` - - diff --git a/website/docs/chapter-04/03_init_files.md b/website/docs/chapter-04/03_init_files.md index 4298f18..ebd47f6 100644 --- a/website/docs/chapter-04/03_init_files.md +++ b/website/docs/chapter-04/03_init_files.md @@ -68,7 +68,7 @@ The following sections are allowed in initialization files: - **`*** Settings ***` Section (required)**: - `Name`: Set a custom name for the suite directory. - `Documentation`: Provide documentation for the suite. - - `Metadata`: Add suite metadata. + - `Metadata`: Add :term[suite metadata]{term="Suite Metadata"}. - `Suite Setup`: Define a keyword to be executed before any tests|tasks or child suites. - `Suite Teardown`: Define a keyword to be executed after all tests|tasks and child suites have completed. - `Test Setup`|`Task Setup`: Set a default setup keyword for all tests|tasks in the suite (can be overridden in lower-level suites or tests|tasks). diff --git a/website/docs/chapter-04/04_tags.md b/website/docs/chapter-04/04_tags.md index b280d8c..ecbff26 100644 --- a/website/docs/chapter-04/04_tags.md +++ b/website/docs/chapter-04/04_tags.md @@ -12,10 +12,13 @@ Recall the purpose of Test|Task Tags in Robot Framework :::: In Robot Framework, **tags** offer a simple yet powerful mechanism for classifying and controlling the execution of tests|tasks. -Tags are free-form text labels that can be assigned to tests|tasks to provide meta information, enable flexible test selection, and organize test results. +Tags are free-form text labels that can be assigned to tests|tasks to group them, enable flexible test selection, and organize test results. Tags are also used to create a statistical summary of the test|task results in the execution protocols. +If named descriptive information shall be stored for a test|task, such as an issue ID, an author, or a requirement reference, :term[test|task metadata]{term="Test Metadata"} is usually a better fit than tags. +Tags are primarily intended for grouping, filtering, and reporting, while metadata stores explicit key-value information. + **Important Note**: Tags are case-insensitive in Robot Framework, but the first appearance of a tag in a test|task is used as the tag name in reports and logs in its current case. @@ -161,4 +164,3 @@ Using your own tags with this prefix may lead to unexpected behavior in test exe - diff --git a/website/src/css/custom.css b/website/src/css/custom.css index f56dc84..581cfa4 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -625,4 +625,11 @@ h6 { break-inside: avoid; page-break-inside: avoid; /* older browser fallback */ } +} + +.named-only-argument-icon { + width: 1.25em; + height: 0.8em; + vertical-align: -0.1em; + fill: currentColor; } \ No newline at end of file diff --git a/website/src/theme/Icon/Copy/index.tsx b/website/src/theme/Icon/Copy/index.tsx new file mode 100644 index 0000000..c32c074 --- /dev/null +++ b/website/src/theme/Icon/Copy/index.tsx @@ -0,0 +1,6 @@ +import type {ReactNode, SVGProps} from 'react'; +import CopyIcon from '@site/static/img/libdoc-icons/copy.svg'; + +export default function IconCopy(props: SVGProps): ReactNode { + return ; +} diff --git a/website/src/theme/Icon/Success/index.tsx b/website/src/theme/Icon/Success/index.tsx new file mode 100644 index 0000000..de61d05 --- /dev/null +++ b/website/src/theme/Icon/Success/index.tsx @@ -0,0 +1,6 @@ +import type {ReactNode, SVGProps} from 'react'; +import CheckIcon from '@site/static/img/libdoc-icons/check.svg'; + +export default function IconSuccess(props: SVGProps): ReactNode { + return ; +} diff --git a/website/static/glossary/glossary.json b/website/static/glossary/glossary.json index c81bbc0..684713c 100644 --- a/website/static/glossary/glossary.json +++ b/website/static/glossary/glossary.json @@ -239,6 +239,12 @@ "abbreviation": "", "definition": "Key–value information defined with the `Metadata` setting in a suite to document attributes such as author, version, or related requirements." }, + { + "term": "Test Metadata", + "aliases": [], + "abbreviation": "", + "definition": "Key–value information defined with the `[Metadata]` setting in a test|task to document attributes such as an issue ID, author, or related requirements." + }, { "term": "Named-Only Argument", "aliases": [], diff --git a/website/static/img/Should_Be_Equal_Docs.png b/website/static/img/Should_Be_Equal_Docs.png index 9b7e9d8..8184673 100644 Binary files a/website/static/img/Should_Be_Equal_Docs.png and b/website/static/img/Should_Be_Equal_Docs.png differ diff --git a/website/static/img/libdoc-icons/check.svg b/website/static/img/libdoc-icons/check.svg new file mode 100644 index 0000000..0d7405a --- /dev/null +++ b/website/static/img/libdoc-icons/check.svg @@ -0,0 +1,14 @@ + + + + + diff --git a/website/static/img/libdoc-icons/copy.svg b/website/static/img/libdoc-icons/copy.svg new file mode 100644 index 0000000..d0eb385 --- /dev/null +++ b/website/static/img/libdoc-icons/copy.svg @@ -0,0 +1,26 @@ + + + + + + diff --git a/website/static/img/libdoc-icons/named-only.svg b/website/static/img/libdoc-icons/named-only.svg new file mode 100644 index 0000000..666cf0c --- /dev/null +++ b/website/static/img/libdoc-icons/named-only.svg @@ -0,0 +1,11 @@ + + + + diff --git a/website/versioned_docs/version-1.0.1/chapter-02/05_keyword_interface.md b/website/versioned_docs/version-1.0.1/chapter-02/05_keyword_interface.md index 59d9649..8f5f5a8 100644 --- a/website/versioned_docs/version-1.0.1/chapter-02/05_keyword_interface.md +++ b/website/versioned_docs/version-1.0.1/chapter-02/05_keyword_interface.md @@ -1,4 +1,6 @@ +import NamedOnlyIcon from '@site/static/img/libdoc-icons/named-only.svg'; + # 2.5 Keyword Interface and Documentation ::::lo[Learning Objectives] @@ -308,7 +310,7 @@ Recall what properties "Named-Only Arguments" have and how they are documented. All arguments that are defined after a "Variable Number of Positional Arguments" (`*varargs`) are "Named-Only Arguments". However it is also possible to create "Named-Only Arguments without a preceding "Variable Number of Positional Arguments". -"Named-Only Arguments" are marked with a "LABEL" sign `🏷` before the argument name in the keyword documentation. +"Named-Only Arguments" are marked with a "LABEL" sign before the argument name in the keyword documentation. Those arguments can not be set positionally. All positional values would be consumed by the "Variable Number of Positional Arguments". So they must be called by their name followed by an equal sign `=` and the value of the argument. @@ -465,4 +467,3 @@ Should Be Equal ${x} expected ignore_case=True formatter=repr - diff --git a/website/versioned_docs/version-1.1.0/chapter-02/05_keyword_interface.md b/website/versioned_docs/version-1.1.0/chapter-02/05_keyword_interface.md index 562e301..077dbe9 100644 --- a/website/versioned_docs/version-1.1.0/chapter-02/05_keyword_interface.md +++ b/website/versioned_docs/version-1.1.0/chapter-02/05_keyword_interface.md @@ -1,4 +1,6 @@ +import NamedOnlyIcon from '@site/static/img/libdoc-icons/named-only.svg'; + # 2.5 Keyword Interface and Documentation ::::lo[Learning Objectives] @@ -318,7 +320,7 @@ Recall what properties "Named-Only Arguments" have and how they are documented. All arguments that are defined after a :term[Variable Number of Positional Arguments] (`*varargs`) are :term[Named-Only Arguments]{term="Named-Only Argument"}. However it is also possible to create :term[Named-Only Arguments]{term="Named-Only Argument"} without a preceding :term[Variable Number of Positional Arguments]. -:term[Named-Only Arguments]{term="Named-Only Argument"} are marked with a "LABEL" sign `🏷` before the argument name in the keyword documentation. +:term[Named-Only Arguments]{term="Named-Only Argument"} are marked with a "LABEL" sign before the argument name in the keyword documentation. Those arguments can not be set positionally. All positional values would be consumed by the :term[Variable Number of Positional Arguments]. So they must be called by their name followed by an equal sign `=` and the value of the argument. @@ -476,4 +478,3 @@ Should Be Equal ${x} expected ignore_case=True formatter=repr -