docs(openspec): archive the doc-viewer-access change

Moves the implemented change to the archive after a green CI run and updates keyword-documentation-rendering, library-documentation-markdown and vscode-documentation-viewer, which now describe the links into the Documentation Viewer, the links of types to their data types and Open as Markdown.

Author: d-biehl

…changes/doc-viewer-access/.openspec.yaml …6-10-03-doc-viewer-access/.openspec.yamlopenspec/changes/doc-viewer-access/.openspec.yaml renamed to openspec/changes/archive/2026-10-03-doc-viewer-access/.openspec.yaml openspec/changes/doc-viewer-access/.openspec.yaml renamed to openspec/changes/archive/2026-10-03-doc-viewer-access/.openspec.yaml

@@ -64,7 +64,7 @@
   - `docs/02_get_started/index.md`: the Python-Markdown row names "Open Documentation (deprecated)" and "Show Documentation (deprecated)".
 
   Verify with `npm run docs:build`.
-- [ ] 7.2 Run `hatch run lint:all`, `hatch run test:test`, `npm run lint` and `npm run compile`, and confirm that all pass. The CI run on Linux, Windows and macOS must be green for the new tests: no hard-coded paths or separators.
+- [x] 7.2 Run `hatch run lint:all`, `hatch run test:test`, `npm run lint` and `npm run compile`, and confirm that all pass. The CI run on Linux, Windows and macOS must be green for the new tests: no hard-coded paths or separators. (CI run 37147588908 on 04d9ca9a, 139 jobs, green.)
 - [x] 7.3 Check at run time in the isolated VS Code harness, on VS Code 1.127 and the installed version:
   - the source action menu on `Library    Collections` lists "Show in Documentation Viewer", "Show in New Documentation Viewer" and "Open Documentation (deprecated)", in this order; "Open Documentation (deprecated)" still opens the Libdoc page;
   - with the bindings of the documentation in `keybindings.json`: Ctrl+Shift+. shows the menu; the binding with the arguments of the preferred action, on a keyword call, an import name and a keyword definition name, shows the viewer at the right place without a menu, the editor keeps the focus, and the menu shows that key next to "Show in Documentation Viewer"; in a comment VS Code reports that no preferred source action is available; Shift+F1 without a binding opens nothing;

…spec/changes/doc-viewer-access/design.md …e/2026-10-03-doc-viewer-access/design.mdopenspec/changes/doc-viewer-access/design.md renamed to openspec/changes/archive/2026-10-03-doc-viewer-access/design.md openspec/changes/doc-viewer-access/design.md renamed to openspec/changes/archive/2026-10-03-doc-viewer-access/design.md

@@ -13,7 +13,7 @@ When a keyword has documented arguments, the rendered keyword documentation SHAL
 - A name that the documentation describes without being an argument of the keyword SHALL get a row of its own, with its name and its description and the other cells empty.
 - A description SHALL be written into its cell as one line: a line break within a paragraph SHALL become a space, and each further paragraph and each list item SHALL start a new line within the cell (`<br>`). A `|` in a description SHALL be escaped, so that every row has the same number of cells.
 
-A keyword without argument descriptions SHALL keep the argument table without the description column. When a return description exists it SHALL be shown with the return type (`**Return Type**: \`T\` — description`, or `**Returns**: description` without a type); raised exceptions SHALL be listed with their descriptions. Outside the full-page documentation of `library-documentation-markdown`, keywords whose documentation is not in Markdown format and has no argument, return or raises description SHALL render exactly as before, except for the corrections of the requirement "Robot-format tables and links convert to valid Markdown".
+A keyword without argument descriptions SHALL keep the argument table without the description column. When a return description exists it SHALL be shown with the return type (`**Return Type**: \`T\` — description`, or `**Returns**: description` without a type); on the full page, the names in `T` link to their data types by the requirement "Data types" of `library-documentation-markdown`. Raised exceptions SHALL be listed with their descriptions. Outside the full-page documentation of `library-documentation-markdown`, keywords whose documentation is not in Markdown format and has no argument, return or raises description SHALL render exactly as before, except for the corrections of the requirement "Robot-format tables and links convert to valid Markdown" and, in VS Code, the links of the requirement "Links in documentation open the Documentation Viewer" of `vscode-documentation-viewer`.
 
 #### Scenario: Standard-library keyword on RF 7.5
 - **WHEN** the hover for `Log` (BuiltIn) is shown on RF 7.5
@@ -39,7 +39,7 @@ A keyword without argument descriptions SHALL keep the argument table without th
 
 #### Scenario: Keyword without descriptions in a non-Markdown library
 - **WHEN** a keyword of a library documented in Robot, reStructuredText, HTML or plain-text format has no Google-style sections, or the installed Robot Framework is older than 7.5
-- **THEN** its hover is identical to the hover before this change, apart from escaped `|` characters in Robot-format table cells and link targets without a `\#` escape
+- **THEN** its hover is identical to the hover before this change, apart from escaped `|` characters in Robot-format table cells, link targets without a `\#` escape, and in VS Code the links to the Documentation Viewer
 
 #### Scenario: Markdown library on an older Robot Framework
 - **WHEN** a library declares `ROBOT_LIBRARY_DOC_FORMAT = "MARKDOWN"` and is documented on RF 7.4
@@ -60,10 +60,10 @@ Signature help SHALL show, for the active parameter, its description followed by
 
 ### Requirement: Markdown reference links are resolved
 
-In documentation declared as Markdown, reference-style links (`[Name]`, `[Name][]`, `[text][Name]`) whose target is a keyword of the same library, a type used by the library, a section of the library introduction or one of Libdoc's default targets (introduction, importing, keywords) SHALL NOT be rendered as literal brackets. In hover, signature help and completion, in the output of `robotcode doc keywords` and `robotcode doc keyword`, and in the `doc` and `short_doc` fields of the JSON output of `robotcode doc` they SHALL be rendered as inline code. In full-document views (REPL `.doc`, `robotcode doc lib` and `browse`, Markdown documentation view) they SHALL be rendered as in-document links, where a reference to a type links to the type's heading in the `Data types` section, by the requirement "Data types" of `library-documentation-markdown`. In the REPL keyword view they SHALL be rendered as navigable keyword links. Reference definitions declared in the library introduction SHALL be applied to keyword documentation. Links inside code spans and fenced code blocks, images and unknown targets SHALL be left unchanged. Matching SHALL ignore case and spaces, as Libdoc does.
+In documentation declared as Markdown, reference-style links (`[Name]`, `[Name][]`, `[text][Name]`) whose target is a keyword of the same library, a type used by the library, a section of the library introduction or one of Libdoc's default targets (introduction, importing, keywords) SHALL NOT be rendered as literal brackets. In hover, signature help and completion, in the output of `robotcode doc keywords` and `robotcode doc keyword`, and in the `doc` and `short_doc` fields of the JSON output of `robotcode doc` they SHALL be rendered as inline code; in VS Code, in hover, signature help, completion and the tooltips of the Keywords view, they SHALL be links to the Documentation Viewer by the requirement "Links in documentation open the Documentation Viewer" of `vscode-documentation-viewer`. In full-document views (REPL `.doc`, `robotcode doc lib` and `browse`, Markdown documentation view) they SHALL be rendered as in-document links, where a reference to a type links to the type's heading in the `Data types` section, by the requirement "Data types" of `library-documentation-markdown`. In the REPL keyword view they SHALL be rendered as navigable keyword links. Reference definitions declared in the library introduction SHALL be applied to keyword documentation. Links inside code spans and fenced code blocks, images and unknown targets SHALL be left unchanged. Matching SHALL ignore case and spaces, as Libdoc does.
 
 #### Scenario: Keyword reference in a hover
-- **WHEN** the hover for `Log` is shown on RF 7.5
+- **WHEN** the hover for `Log` is shown on RF 7.5 to a language client other than the VS Code extension
 - **THEN** `[Set Log Level]` is rendered as `` `Set Log Level` `` and `[String representations]` as `` `String representations` ``
 
 #### Scenario: Keyword reference in a full-document view
@@ -87,6 +87,10 @@ In documentation declared as Markdown, reference-style links (`[Name]`, `[Name][
 - **WHEN** a documentation contains `` `[Tags]` `` in a code span or `[1]` with a keyword-local definition
 - **THEN** they are rendered unchanged
 
+#### Scenario: Keyword reference in a VS Code hover
+- **WHEN** the hover for `Log` is shown in VS Code on RF 7.5
+- **THEN** `Set Log Level` and `String representations` are links that show `BuiltIn` in the Documentation Viewer at that keyword and that section
+
 ### Requirement: Markdown library introductions are normalised
 
 For libraries documented in Markdown, a `%TOC%` line in the introduction SHALL be replaced by a two-level table of contents of the introduction's headings; ATX headings SHALL be shifted one level down (`#` → `##`) as Robot-format headings are today; GitHub-style admonitions (`> [!NOTE]`, `> [!WARNING]`, …) SHALL be rendered as block quotes with a bold label; fenced code, tables and raw HTML SHALL be left unchanged. The backtick auto-linking applied to Robot-format documentation SHALL NOT be applied to Markdown documentation.
@@ -101,7 +105,7 @@ For libraries documented in Markdown, a `%TOC%` line in the introduction SHALL b
 
 ### Requirement: Robot-format tables and links convert to valid Markdown
 
-When documentation in Robot Framework's format is converted to Markdown, on every surface and every supported Robot Framework version, a `|` inside the content of a table cell SHALL be escaped, so that every table row keeps the number of cells Robot Framework gives it. No link target SHALL contain the escaped `\#`: links converted from Robot-format links and URLs, and the links from backtick names to headings of the same documentation, SHALL be written with `#`. Link texts and all other text SHALL be converted as before, apart from the names in single backticks that the full page links (requirement "Names in Robot-format documentation" of `library-documentation-markdown`).
+When documentation in Robot Framework's format is converted to Markdown, on every surface and every supported Robot Framework version, a `|` inside the content of a table cell SHALL be escaped, so that every table row keeps the number of cells Robot Framework gives it. No link target SHALL contain the escaped `\#`: links converted from Robot-format links and URLs, and the links from backtick names to headings of the same documentation, SHALL be written with `#`. Link texts and all other text SHALL be converted as before, apart from the names in single backticks that the full page links (requirement "Names in Robot-format documentation" of `library-documentation-markdown`) and, in VS Code, the links of the requirement "Links in documentation open the Documentation Viewer" of `vscode-documentation-viewer`, which replace these links there.
 
 #### Scenario: Pipe inside a table cell
 - **WHEN** the hover for `Should Match Regexp` (BuiltIn) is shown on RF 6.1
@@ -112,7 +116,7 @@ When documentation in Robot Framework's format is converted to Markdown, on ever
 - **THEN** the rendered documentation contains the link `[docs](http://example.com/x.html#frag)`
 
 #### Scenario: Library introduction on an older Robot Framework
-- **WHEN** the hover for a `BuiltIn` import is shown on RF 6.1
+- **WHEN** the hover for a `BuiltIn` import is shown on RF 6.1 in a language client other than the VS Code extension
 - **THEN** it contains the links `[eval](http://docs.python.org/library/functions.html#eval)` and `[str](#str)`
 - **AND** no link target contains `\#`
 
@@ -126,8 +130,8 @@ Library documentation SHALL show the scope of a library as Robot Framework's Lib
 
 ### Requirement: Links to headings use GitHub anchors
 
-Links to headings within library documentation, such as the table of contents that replaces `%TOC%` and the links from backtick names to headings, SHALL point to the anchor that GitHub gives the heading, by the rule of the requirement "Anchors" of `library-documentation-markdown`.
+Links to headings within library documentation, such as the table of contents that replaces `%TOC%` and the links from backtick names to headings, SHALL point to the anchor that GitHub gives the heading, by the rule of the requirement "Anchors" of `library-documentation-markdown`. In VS Code, such a link carries that anchor to the Documentation Viewer instead, by the requirement "Links in documentation open the Documentation Viewer" of `vscode-documentation-viewer`.
 
 #### Scenario: Library hover with a table of contents
-- **WHEN** the hover for a `DateTime` import is shown on RF 7.5
+- **WHEN** the hover for a `DateTime` import is shown on RF 7.5 in a language client other than the VS Code extension
 - **THEN** its table of contents links `` `TODAY` and `NOW` `` to `#today-and-now`

…ec/changes/doc-viewer-access/proposal.md …2026-10-03-doc-viewer-access/proposal.mdopenspec/changes/doc-viewer-access/proposal.md renamed to openspec/changes/archive/2026-10-03-doc-viewer-access/proposal.md openspec/changes/doc-viewer-access/proposal.md renamed to openspec/changes/archive/2026-10-03-doc-viewer-access/proposal.md

@@ -78,7 +78,9 @@ The `Keywords` section SHALL start with an index: a list with one link per keywo
 
 ### Requirement: Data types
 
-With Robot Framework 6.1 or newer, the `Data types` section SHALL document every type that Libdoc documents for the library's keywords, each with its kind and documentation, the allowed values of an enumeration and the structure of a typed dictionary. A table of contents that replaces `%TOC%` SHALL list `Data types` after `Keywords` when the page has the section. In the introduction and in the documentation of keywords, including the descriptions of arguments, return values and exceptions, a reference to a documented type, as a Markdown reference link such as `[Color]` or as a name in single backticks such as `` `Color` `` in Robot Framework's format, SHALL link to the anchor that the requirement "Anchors" gives the type's heading, also when that anchor is numbered. Argument names, the argument and return types of the `Arguments:` parts, and code in double backticks in Robot Framework's format SHALL stay inline code, also when they equal the name of a type.
+With Robot Framework 6.1 or newer, the `Data types` section SHALL document every type that Libdoc documents for the library's keywords, each with its kind and documentation, the allowed values of an enumeration and the structure of a typed dictionary. A table of contents that replaces `%TOC%` SHALL list `Data types` after `Keywords` when the page has the section. In the introduction and in the documentation of keywords, including the descriptions of arguments, return values and exceptions, a reference to a documented type, as a Markdown reference link such as `[Color]` or as a name in single backticks such as `` `Color` `` in Robot Framework's format, SHALL link to the anchor that the requirement "Anchors" gives the type's heading, also when that anchor is numbered.
+
+In the argument tables of the keywords and of the initializer, and in the return types, each name of a type that Libdoc maps to a documented type, such as `int` to `integer`, SHALL link to the anchor that the requirement "Anchors" gives that type's heading, also when that anchor is numbered, and SHALL stay inline code inside the link. The rest of a type, such as brackets, the values of a `Literal` and the names of types without documentation, SHALL stay inline code, and the members of a union SHALL stay separated by `|`. A type that names no documented type SHALL be written as before, and every row of an argument table SHALL keep its number of cells. Argument names and code in double backticks in Robot Framework's format SHALL stay inline code, also when they equal the name of a type.
 
 #### Scenario: Enumeration
 - **WHEN** the page of a library with the keyword `paint(self, shade: Color)` and an `Enum` `Color` is rendered on RF 6.1 or newer
@@ -94,17 +96,31 @@ With Robot Framework 6.1 or newer, the `Data types` section SHALL document every
 
 #### Scenario: Argument and code named like a type
 - **WHEN** the keyword of the scenario "Type reference" also has the argument `color: str`, and its Robot-format documentation also writes the code ``` ``color`` ```
-- **THEN** the reference to `Color` is the only link to `#color-enum`
-- **AND** the argument name `color`, the argument type `Color` and the code `color` are inline code
+- **THEN** the argument name `color` and the code `color` are inline code
+- **AND** the type of `shade` is the link ``[`Color`](#color-enum)``, and the type `str` of `color` links to the heading `string (Standard)`
 
 #### Scenario: Type heading with a repeated anchor
 - **WHEN** the library of the scenario "Type reference" is documented in Markdown and also has the keyword `Color Enum`
 - **THEN** the heading of `Color Enum` has the anchor `color-enum` and the heading `Color (Enum)` the anchor `color-enum-1`
-- **AND** `[Color]` links to `#color-enum-1`
+- **AND** `[Color]` and the type of `shade` link to `#color-enum-1`
+
+#### Scenario: Types of XML
+- **WHEN** the page of `XML` is rendered on RF 7.4 or 7.5
+- **THEN** in the argument table of `Parse Xml`, the type `Source` is the link ``[`Source`](#source-custom)`` and `bool` links to `#boolean-standard`
+- **AND** its return type is the link ``[`Element`](#element-custom)``
+
+#### Scenario: Nested types, unions and literals
+- **WHEN** the page of a library is rendered on RF 7.0 or newer, whose keyword has the arguments `values: list[int]`, `limit: int | None` and `mode: Literal['a', 'b']`
+- **THEN** `list`, `int`, `None` and `Literal` link to their headings in `Data types`, the brackets and `'a', 'b'` are inline code, `int` and `None` are separated by `|`
+- **AND** every row of the argument table has as many cells as its header
+
+#### Scenario: Type without documentation
+- **WHEN** the page of `BuiltIn` is rendered on RF 7.5
+- **THEN** the type `Collection` of the argument `container` of `Should Contain` is inline code
 
 ### Requirement: Names in Robot-format documentation
 
-In documentation in Robot Framework's format, a name in single backticks SHALL link to the heading it names, as Libdoc's HTML links it, also when the name wraps across two lines of a paragraph and whatever text comes before it on the line. The link SHALL point to the heading whose title is the name, also when another heading has the same anchor text. This applies in the introduction and in the documentation of keywords, including the descriptions of arguments, return values and exceptions. The name can be a keyword, a section of the introduction, one of the default sections (introduction, importing, keywords) or a data type; data types are linked by the requirement "Data types". Names in headings and in preformatted text SHALL stay as they are. Argument names, the argument and return types of the `Arguments:` parts, and code in double backticks SHALL stay inline code, also when they equal the name of a keyword or a section, as they do for data types.
+In documentation in Robot Framework's format, a name in single backticks SHALL link to the heading it names, as Libdoc's HTML links it, also when the name wraps across two lines of a paragraph and whatever text comes before it on the line. The link SHALL point to the heading whose title is the name, also when another heading has the same anchor text. This applies in the introduction and in the documentation of keywords, including the descriptions of arguments, return values and exceptions. The name can be a keyword, a section of the introduction, one of the default sections (introduction, importing, keywords) or a data type; data types are linked by the requirement "Data types". Names in headings and in preformatted text SHALL stay as they are. Argument names and code in double backticks SHALL stay inline code, also when they equal the name of a keyword, a section or a data type; argument and return types link only to data types, by the requirement "Data types".
 
 #### Scenario: Keyword and section names
 - **WHEN** the page of a library documented in Robot Framework's format is rendered, whose introduction has the section `= Section =` and whose keyword `Zeta Kw` is documented with `` `Alpha Kw` `` and `` `Section` ``