robotcode-robot 2.6.2__py3-none-any.whl → 2.8.0.dev548__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. robotcode/robot/__version__.py +1 -1
  2. robotcode/robot/config/loader.py +18 -5
  3. robotcode/robot/config/model.py +258 -61
  4. robotcode/robot/diagnostics/analyzer_result.py +1 -0
  5. robotcode/robot/diagnostics/data_cache.py +12 -1
  6. robotcode/robot/diagnostics/diagnostic_rules.py +75 -0
  7. robotcode/robot/diagnostics/diagnostics_modifier.py +83 -43
  8. robotcode/robot/diagnostics/document_cache_helper.py +158 -17
  9. robotcode/robot/diagnostics/errors.py +7 -0
  10. robotcode/robot/diagnostics/import_resolver.py +178 -12
  11. robotcode/robot/diagnostics/imports_manager.py +556 -220
  12. robotcode/robot/diagnostics/library_doc.py +874 -162
  13. robotcode/robot/diagnostics/namespace.py +84 -18
  14. robotcode/robot/diagnostics/namespace_analyzer.py +59 -16
  15. robotcode/robot/diagnostics/project_index.py +88 -13
  16. robotcode/robot/diagnostics/scope_tree.py +2 -2
  17. robotcode/robot/diagnostics/semantic_analyzer/analyzer.py +790 -201
  18. robotcode/robot/diagnostics/semantic_analyzer/enums.py +39 -2
  19. robotcode/robot/diagnostics/semantic_analyzer/json_dump.py +364 -0
  20. robotcode/robot/diagnostics/semantic_analyzer/model.py +72 -11
  21. robotcode/robot/diagnostics/semantic_analyzer/nodes.py +7 -1
  22. robotcode/robot/diagnostics/semantic_analyzer/variable_tokenizer.py +218 -112
  23. robotcode/robot/diagnostics/workspace_config.py +3 -0
  24. robotcode/robot/utils/markdown_docs.py +733 -0
  25. robotcode/robot/utils/markdownformatter.py +57 -12
  26. robotcode/robot/utils/match.py +13 -0
  27. robotcode/robot/utils/robot_patching.py +4 -0
  28. robotcode/robot/utils/variables.py +3 -0
  29. {robotcode_robot-2.6.2.dist-info → robotcode_robot-2.8.0.dev548.dist-info}/METADATA +4 -3
  30. robotcode_robot-2.8.0.dev548.dist-info/RECORD +48 -0
  31. {robotcode_robot-2.6.2.dist-info → robotcode_robot-2.8.0.dev548.dist-info}/WHEEL +1 -1
  32. robotcode_robot-2.6.2.dist-info/RECORD +0 -46
@@ -25,6 +25,7 @@ from typing import (
25
25
  Iterator,
26
26
  List,
27
27
  Literal,
28
+ Mapping,
28
29
  NamedTuple,
29
30
  Optional,
30
31
  Sequence,
@@ -41,6 +42,7 @@ from robot.libdocpkg import LibraryDocumentation
41
42
  from robot.libdocpkg.htmlwriter import LibdocHtmlWriter
42
43
  from robot.libdocpkg.robotbuilder import KeywordDocBuilder
43
44
  from robot.libraries import STDLIBS
45
+ from robot.model.tags import Tags as RobotTags
44
46
  from robot.output.logger import LOGGER
45
47
  from robot.output.loggerhelper import AbstractLogger
46
48
  from robot.parsing.lexer.tokens import Token
@@ -60,6 +62,8 @@ from robot.running.arguments.embedded import EmbeddedArguments
60
62
  from robot.running.builder.transformers import ResourceBuilder
61
63
  from robot.running.outputcapture import OutputCapturer
62
64
  from robot.running.runkwregister import RUN_KW_REGISTER
65
+ from robot.utils.escaping import unescape
66
+ from robot.utils.htmlformatters import HeaderFormatter as RobotHeaderFormatter
63
67
  from robot.utils.importer import Importer
64
68
  from robot.utils.robotpath import find_file as robot_find_file
65
69
  from robot.variables import Variables
@@ -76,7 +80,28 @@ from ..utils.ast import (
76
80
  range_from_token,
77
81
  strip_variable_token,
78
82
  )
79
- from ..utils.markdownformatter import MarkDownFormatter
83
+ from ..utils.markdown_docs import (
84
+ REFERENCE_KEYWORD,
85
+ REFERENCE_LINK,
86
+ REFERENCE_SECTION,
87
+ REFERENCE_TYPE,
88
+ LinkResolver,
89
+ ReferenceTarget,
90
+ code_span,
91
+ code_span_variables,
92
+ escape_link_text,
93
+ extract_reference_definitions,
94
+ heading_anchors,
95
+ iter_headings,
96
+ normalize_markdown_doc,
97
+ normalize_reference,
98
+ replace_toc,
99
+ section_anchors,
100
+ shift_headings,
101
+ slugify,
102
+ unique_reference_labels,
103
+ )
104
+ from ..utils.markdownformatter import MarkDownFormatter, NameLinker
80
105
  from ..utils.match import normalize, normalize_namespace
81
106
  from ..utils.robot_patching import patch_variable_not_found
82
107
  from ..utils.variables import contains_variable, replace_curdir_in_variable_values, search_variable
@@ -120,6 +145,9 @@ if RF_VERSION >= (7, 4):
120
145
  from robot.api.types import KeywordArgument as _KeywordArgument
121
146
  from robot.api.types import KeywordName as _KeywordName
122
147
 
148
+ if RF_VERSION >= (7, 5):
149
+ from robot.running.docstringparser import parse_docstring
150
+
123
151
  patch_variable_not_found()
124
152
 
125
153
  RUN_KEYWORD_NAMES = [
@@ -173,6 +201,7 @@ ROBOT_FILE_EXTENSION = ".robot"
173
201
  RESOURCE_FILE_EXTENSION = ".resource"
174
202
  REST_EXTENSIONS = {".rst", ".rest"}
175
203
  JSON_EXTENSIONS = {".json", ".rsrc"}
204
+ MARKDOWN_EXTENSIONS = {".md", ".markdown"}
176
205
 
177
206
  ALLOWED_RESOURCE_FILE_EXTENSIONS = (
178
207
  {
@@ -184,23 +213,186 @@ ALLOWED_RESOURCE_FILE_EXTENSIONS = (
184
213
  if RF_VERSION >= (6, 1)
185
214
  else {ROBOT_FILE_EXTENSION, RESOURCE_FILE_EXTENSION, *REST_EXTENSIONS}
186
215
  )
216
+ if RF_VERSION >= (7, 5):
217
+ ALLOWED_RESOURCE_FILE_EXTENSIONS |= MARKDOWN_EXTENSIONS
187
218
 
188
219
  ALLOWED_VARIABLES_FILE_EXTENSIONS = (
189
220
  {".py", ".yml", ".yaml", ".json"} if RF_VERSION >= (6, 1) else {".py", ".yml", ".yaml"}
190
221
  )
191
222
  ROBOT_DOC_FORMAT = "ROBOT"
192
223
  REST_DOC_FORMAT = "REST"
224
+ MARKDOWN_DOC_FORMAT = "MARKDOWN"
225
+ HTML_DOC_FORMAT = "HTML"
193
226
 
194
227
  _F = TypeVar("_F", bound=Callable[..., Any])
195
228
 
196
229
 
230
+ def _page_heading_shift(doc_format: str, levels: int) -> Optional[Callable[[str], str]]:
231
+ """Moves the Markdown headings of documentation on the full page `levels` down.
232
+
233
+ Robot Framework's format and Markdown already start at level 2, plain text at
234
+ level 1. HTML and reStructuredText keep their HTML headings.
235
+ """
236
+ if doc_format in (REST_DOC_FORMAT, HTML_DOC_FORMAT):
237
+ return None
238
+ if doc_format not in (ROBOT_DOC_FORMAT, MARKDOWN_DOC_FORMAT):
239
+ levels += 1
240
+ return lambda doc: shift_headings(doc, levels)
241
+
242
+
243
+ # A run of `#` after a space at the end of a keyword name would close its ATX heading: `### Use C #` shows "Use C".
244
+ _RE_CLOSING_HASHES = re.compile(r"(\s)(#+)$")
245
+ _RE_ESCAPED_CLOSING_HASHES = re.compile(r"(\s)\\(#+)$")
246
+
247
+
248
+ def _heading_name(name: str) -> str:
249
+ """A keyword name as the title of its heading: a closing run of `#` escaped."""
250
+ return _RE_CLOSING_HASHES.sub(r"\1\\\2", name)
251
+
252
+
253
+ def _heading_title_name(title: str) -> str:
254
+ """The keyword name of a heading title that `_heading_name` wrote."""
255
+ return _RE_ESCAPED_CLOSING_HASHES.sub(r"\1\2", title)
256
+
257
+
258
+ def _match_heading_anchors(headings: List[Tuple[str, str]], titles: List[Set[str]]) -> List[str]:
259
+ """For each set of titles, in order, the anchor of the next heading that has one
260
+ of them, or an empty anchor. A missing heading leaves the following ones alone."""
261
+ anchors: List[str] = []
262
+ position = 0
263
+ for entry_titles in titles:
264
+ index = next((i for i in range(position, len(headings)) if headings[i][0] in entry_titles), None)
265
+ if index is None:
266
+ anchors.append("")
267
+ else:
268
+ anchors.append(headings[index][1])
269
+ position = index + 1
270
+ return anchors
271
+
272
+
273
+ _TYPE_NAME = "name"
274
+ _TYPE_UNION = "union"
275
+ _TYPE_OTHER = "other"
276
+ _RE_TYPE_TOKEN = re.compile(
277
+ r"""(?P<union>\s*\|\s*)|(?P<quoted>'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")|(?P<name>[^\s\[\],|'"]+)|(?P<other>.)""",
278
+ re.DOTALL,
279
+ )
280
+
281
+
282
+ def _type_tokens(type_string: str) -> List[Tuple[str, str]]:
283
+ """The parts of a type as names, union separators and other parts; the
284
+ content of `Literal[...]` is one part, its values are no names."""
285
+ tokens: List[Tuple[str, str]] = []
286
+ position = 0
287
+ while position < len(type_string):
288
+ match = cast("re.Match[str]", _RE_TYPE_TOKEN.match(type_string, position))
289
+ position = match.end()
290
+ name = match.group("name")
291
+ if match.group("union") is not None:
292
+ tokens.append((_TYPE_UNION, match.group(0)))
293
+ elif name is None:
294
+ tokens.append((_TYPE_OTHER, match.group(0)))
295
+ else:
296
+ tokens.append((_TYPE_NAME, name))
297
+ if name.rsplit(".", 1)[-1] == "Literal" and type_string.startswith("[", position):
298
+ end = _literal_end(type_string, position)
299
+ tokens.append((_TYPE_OTHER, type_string[position:end]))
300
+ position = end
301
+ return tokens
302
+
303
+
304
+ def _literal_end(type_string: str, start: int) -> int:
305
+ """The end of the brackets of a `Literal` that start at `start`, after the closing bracket."""
306
+ depth = 0
307
+ quote: Optional[str] = None
308
+ position = start
309
+ while position < len(type_string):
310
+ character = type_string[position]
311
+ if quote is not None:
312
+ if character == "\\":
313
+ position += 1
314
+ elif character == quote:
315
+ quote = None
316
+ elif character in "'\"":
317
+ quote = character
318
+ elif character == "[":
319
+ depth += 1
320
+ elif character == "]":
321
+ depth -= 1
322
+ if depth == 0:
323
+ return position + 1
324
+ position += 1
325
+ return position
326
+
327
+
328
+ def _type_markdown(
329
+ type_string: str,
330
+ type_docs: Optional[Mapping[str, str]],
331
+ link_resolver: Optional[LinkResolver],
332
+ in_table: bool,
333
+ ) -> str:
334
+ """A type as inline code, in which each name that Libdoc maps to a documented
335
+ type links to it, if `link_resolver` gives a link for that type.
336
+
337
+ Union members stay separated by `|`. Without such a link, the type is written as before.
338
+ """
339
+ plain = type_string.replace("|", "\\|") if in_table else type_string
340
+ if not type_docs or link_resolver is None:
341
+ return f"`{plain}`"
342
+
343
+ parts: List[str] = []
344
+ code = ""
345
+ linked = False
346
+
347
+ def add_code() -> None:
348
+ nonlocal code
349
+ if code:
350
+ parts.append(code_span(code.replace("|", "\\|") if in_table else code))
351
+ code = ""
352
+
353
+ for kind, token in _type_tokens(type_string):
354
+ if kind == _TYPE_UNION:
355
+ add_code()
356
+ parts.append(" \\| " if in_table else " | ")
357
+ continue
358
+ link = link_resolver(REFERENCE_TYPE, type_docs[token]) if kind == _TYPE_NAME and token in type_docs else None
359
+ if link is None:
360
+ code += token
361
+ else:
362
+ add_code()
363
+ parts.append(f"[{code_span(token)}]({link})")
364
+ linked = True
365
+ add_code()
366
+
367
+ return "".join(parts) if linked else f"`{plain}`"
368
+
369
+
370
+ def _name_linker(
371
+ targets: Optional[Mapping[str, ReferenceTarget]], link_resolver: Optional[LinkResolver]
372
+ ) -> Optional[NameLinker]:
373
+ """Links the names in single backticks of documentation in Robot Framework's
374
+ format to the keyword, section or type they name, as Libdoc links them."""
375
+ if not targets or link_resolver is None:
376
+ return None
377
+
378
+ def link(name: str) -> Optional[str]:
379
+ target = targets.get(normalize_reference(name))
380
+ if target is None or target.kind == REFERENCE_LINK:
381
+ return None
382
+ return link_resolver(target.kind, target.name)
383
+
384
+ return link
385
+
386
+
197
387
  def convert_from_rest(text: str) -> str:
198
388
  try:
199
389
  from docutils.core import publish_parts
390
+ from docutils.writers.html5_polyglot import Writer
200
391
 
201
392
  parts = publish_parts(
202
393
  text,
203
- writer_name="html5",
394
+ # an instance, which every Docutils version takes; Docutils deprecates `writer_name`
395
+ writer=Writer(),
204
396
  settings_overrides={"syntax_highlight": "none"},
205
397
  )
206
398
 
@@ -381,7 +573,15 @@ class TypeDoc:
381
573
  )
382
574
  )
383
575
 
384
- def to_markdown(self, header_level: int = 2, only_doc: bool = False) -> str:
576
+ def to_markdown(
577
+ self,
578
+ header_level: int = 2,
579
+ only_doc: bool = False,
580
+ *,
581
+ link_resolver: Optional[LinkResolver] = None,
582
+ reference_targets: Optional[Mapping[str, ReferenceTarget]] = None,
583
+ modify_doc_handler: Optional[Callable[[str], str]] = None,
584
+ ) -> str:
385
585
  result = ""
386
586
 
387
587
  result += f"##{'#' * header_level} {self.name} ({self.type})\n\n"
@@ -391,11 +591,15 @@ class TypeDoc:
391
591
  result += "\n\n"
392
592
 
393
593
  if self.doc_format == ROBOT_DOC_FORMAT:
394
- result += MarkDownFormatter().format(self.doc)
594
+ doc = MarkDownFormatter().format(self.doc)
395
595
  elif self.doc_format == REST_DOC_FORMAT:
396
- result += convert_from_rest(self.doc)
596
+ doc = convert_from_rest(self.doc)
597
+ elif self.doc_format == MARKDOWN_DOC_FORMAT:
598
+ doc = normalize_markdown_doc(self.doc, reference_targets, link_resolver)
397
599
  else:
398
- result += self.doc
600
+ doc = self.doc
601
+
602
+ result += modify_doc_handler(doc) if modify_doc_handler is not None else doc
399
603
 
400
604
  if not only_doc:
401
605
  if self.members:
@@ -475,6 +679,9 @@ class ArgumentInfo:
475
679
  literal_values: Optional[List[str]] = None
476
680
  is_keyword_name: bool = False
477
681
  is_keyword_argument: bool = False
682
+ doc: str = field(default="", compare=False)
683
+ # used type name -> name of the type documentation, as Libdoc computes it
684
+ type_docs: Optional[Dict[str, str]] = field(default=None, compare=False)
478
685
 
479
686
  def __setstate__(self, state: Any) -> None:
480
687
  if isinstance(state, tuple):
@@ -492,18 +699,19 @@ class ArgumentInfo:
492
699
  return None
493
700
 
494
701
  values: List[str] = []
495
-
496
- def _collect(ti: Any) -> None:
497
- if ti.type is Literal and ti.nested:
498
- for nested in ti.nested:
499
- values.append(nested.name.strip("'"))
500
- elif ti.is_union and ti.nested:
501
- for nested in ti.nested:
502
- _collect(nested)
503
-
504
- _collect(type_info)
702
+ ArgumentInfo._collect_literal_values(type_info, values)
505
703
  return values or None
506
704
 
705
+ # a static method rather than an inner function: an inner function that calls itself is a reference cycle
706
+ @staticmethod
707
+ def _collect_literal_values(type_info: Any, values: List[str]) -> None:
708
+ if type_info.type is Literal and type_info.nested:
709
+ for nested in type_info.nested:
710
+ values.append(nested.name.strip("'"))
711
+ elif type_info.is_union and type_info.nested:
712
+ for nested in type_info.nested:
713
+ ArgumentInfo._collect_literal_values(nested, values)
714
+
507
715
  else:
508
716
 
509
717
  @staticmethod
@@ -741,6 +949,11 @@ class KeywordDoc(SourceEntity):
741
949
  args_to_process: Optional[int] = field(default=None, compare=False)
742
950
  deprecated: bool = field(default=False, compare=False)
743
951
  return_type: Optional[str] = field(default=None, compare=False)
952
+ return_doc: str = field(default="", compare=False)
953
+ raises: Optional[List[Tuple[str, str]]] = field(default=None, compare=False)
954
+ return_type_docs: Optional[Dict[str, str]] = field(default=None, compare=False)
955
+ # documentation of arguments the keyword does not have, e.g. names accepted via `**kwargs`
956
+ extra_argument_docs: Optional[List[Tuple[str, str]]] = field(default=None, compare=False)
744
957
 
745
958
  parent: Optional[LibraryDoc] = field(default=None, init=False)
746
959
  _hash_value: int = field(default=0, init=False, compare=False, hash=False, repr=False)
@@ -822,9 +1035,21 @@ class KeywordDoc(SourceEntity):
822
1035
  def __getstate__(self) -> Dict[str, Any]:
823
1036
  return {slot: getattr(self, slot) for slot in self._all_slots() if slot not in self._EXCLUDED_FROM_STATE}
824
1037
 
1038
+ @classmethod
1039
+ def _field_default(cls, name: str) -> Any:
1040
+ f = cls.__dataclass_fields__.get(name)
1041
+ if f is None:
1042
+ return None
1043
+ if f.default is not MISSING:
1044
+ return f.default
1045
+ if f.default_factory is not MISSING:
1046
+ return f.default_factory()
1047
+ return None
1048
+
825
1049
  def __setstate__(self, state: Dict[str, Any]) -> None:
826
1050
  for slot in self._all_slots():
827
- setattr(self, slot, state.get(slot, None))
1051
+ # a state written before a field existed gets the default of that field
1052
+ setattr(self, slot, state[slot] if slot in state else self._field_default(slot))
828
1053
  self._matcher = None
829
1054
  self.parent = None
830
1055
  self._stable_id = ""
@@ -933,11 +1158,17 @@ class KeywordDoc(SourceEntity):
933
1158
  header_level: int = 2,
934
1159
  add_type: bool = True,
935
1160
  modify_doc_handler: Optional[Callable[[str], str]] = None,
1161
+ *,
1162
+ link_resolver: Optional[LinkResolver] = None,
1163
+ reference_targets: Optional[Mapping[str, ReferenceTarget]] = None,
936
1164
  ) -> str:
937
1165
  result = ""
938
1166
 
1167
+ # a library that renders all of its keywords builds the targets once
1168
+ targets = reference_targets if reference_targets is not None else self.get_reference_targets()
1169
+
939
1170
  if add_signature:
940
- result += self._get_signature(header_level, add_type)
1171
+ result += self._get_signature(header_level, add_type, link_resolver, targets)
941
1172
 
942
1173
  if self.doc:
943
1174
  if result:
@@ -945,22 +1176,175 @@ class KeywordDoc(SourceEntity):
945
1176
 
946
1177
  result += f"##{'#' * header_level} Documentation:\n"
947
1178
 
948
- doc: Optional[str] = None
949
- if self.doc_format == ROBOT_DOC_FORMAT:
950
- doc = MarkDownFormatter().format(self.doc)
951
- elif self.doc_format == REST_DOC_FORMAT:
952
- doc = convert_from_rest(self.doc)
1179
+ doc = self.format_text(self.doc, link_resolver=link_resolver, reference_targets=targets)
1180
+ if modify_doc_handler is not None:
1181
+ doc = modify_doc_handler(doc)
1182
+ result += doc
1183
+
1184
+ return result
1185
+
1186
+ def format_text(
1187
+ self,
1188
+ text: str,
1189
+ *,
1190
+ link_resolver: Optional[LinkResolver] = None,
1191
+ reference_targets: Optional[Mapping[str, ReferenceTarget]] = None,
1192
+ ) -> str:
1193
+ """Convert documentation text of this keyword to Markdown.
1194
+
1195
+ Without a `link_resolver`, references become inline code, as in the hover.
1196
+ """
1197
+ targets = reference_targets if reference_targets is not None else self.get_reference_targets()
1198
+
1199
+ if self.doc_format == ROBOT_DOC_FORMAT:
1200
+ return MarkDownFormatter(_name_linker(targets, link_resolver)).format(text)
1201
+ if self.doc_format == REST_DOC_FORMAT:
1202
+ return convert_from_rest(text)
1203
+ if self.doc_format == MARKDOWN_DOC_FORMAT:
1204
+ return normalize_markdown_doc(text, targets, link_resolver)
1205
+ return text
1206
+
1207
+ def get_reference_targets(self) -> Optional[Mapping[str, ReferenceTarget]]:
1208
+ """What reference links can point to, only documentation written in Markdown has them."""
1209
+ if self.parent is None or not self.doc_format == MARKDOWN_DOC_FORMAT:
1210
+ return None
1211
+ return self.parent.get_reference_targets()
1212
+
1213
+ def _format_doc_fragment(
1214
+ self,
1215
+ text: str,
1216
+ link_resolver: Optional[LinkResolver],
1217
+ targets: Optional[Mapping[str, ReferenceTarget]],
1218
+ ) -> str:
1219
+ if self.doc_format == ROBOT_DOC_FORMAT:
1220
+ text = MarkDownFormatter(_name_linker(targets, link_resolver)).format(text)
1221
+ elif self.doc_format == MARKDOWN_DOC_FORMAT:
1222
+ text = normalize_markdown_doc(text, targets, link_resolver)
1223
+ return re.sub(r"\n{3,}", "\n\n", text.strip())
1224
+
1225
+ def argument_to_markdown(
1226
+ self,
1227
+ argument: ArgumentInfo,
1228
+ *,
1229
+ link_resolver: Optional[LinkResolver] = None,
1230
+ reference_targets: Optional[Mapping[str, ReferenceTarget]] = None,
1231
+ ) -> Optional[str]:
1232
+ """The description of an argument followed by the documentation of its types."""
1233
+ # a caller that renders several arguments of a keyword builds the targets once
1234
+ targets = reference_targets if reference_targets is not None else self.get_reference_targets()
1235
+ parts: List[str] = []
1236
+ if argument.doc:
1237
+ parts.append(self._format_doc_fragment(argument.doc, link_resolver, targets))
1238
+ if self.parent is not None:
1239
+ parts.extend(
1240
+ t.to_markdown(link_resolver=link_resolver, reference_targets=targets)
1241
+ for t in self.parent.get_types_for_argument(argument)
1242
+ )
1243
+ return "\n\n---\n\n".join(parts) or None
1244
+
1245
+ def _format_description(
1246
+ self,
1247
+ text: str,
1248
+ link_resolver: Optional[LinkResolver],
1249
+ targets: Optional[Mapping[str, ReferenceTarget]],
1250
+ ) -> str:
1251
+ """A description of an argument, the return value or an exception as part of a list item."""
1252
+ lines = self._format_doc_fragment(text, link_resolver, targets).splitlines()
1253
+ if not lines:
1254
+ return ""
1255
+ # a description that starts with a list or a block quote needs its own block
1256
+ first = "\n\n " if re.match(r"([-+*>]|\d+[.)])\s", lines[0]) else ""
1257
+ return first + "\n".join([lines[0], *(f" {line}" if line else "" for line in lines[1:])])
1258
+
1259
+ @staticmethod
1260
+ def _get_argument_prefix(argument: ArgumentInfo) -> str:
1261
+ if argument.kind == KeywordArgumentKind.VAR_POSITIONAL:
1262
+ return "*"
1263
+ if argument.kind == KeywordArgumentKind.VAR_NAMED:
1264
+ return "**"
1265
+ if argument.kind == KeywordArgumentKind.NAMED_ONLY:
1266
+ return "🏷"
1267
+ if argument.kind == KeywordArgumentKind.POSITIONAL_ONLY:
1268
+ return "⟶"
1269
+ return ""
1270
+
1271
+ def _description_cell(
1272
+ self,
1273
+ text: str,
1274
+ link_resolver: Optional[LinkResolver],
1275
+ targets: Optional[Mapping[str, ReferenceTarget]],
1276
+ ) -> str:
1277
+ """A description as the single line of a table cell.
1278
+
1279
+ The lines of a paragraph are joined with a space; a further paragraph,
1280
+ a list item and each line of a code block start a new line in the cell.
1281
+ """
1282
+ cell_lines: List[str] = []
1283
+ new_line = True
1284
+ in_code = False
1285
+ for raw_line in self._format_doc_fragment(text, link_resolver, targets).splitlines():
1286
+ line = raw_line.strip()
1287
+ if re.match(r"(`{3,}|~{3,})", line):
1288
+ in_code = not in_code
1289
+ new_line = True
1290
+ elif not line:
1291
+ new_line = True
1292
+ elif in_code or new_line or re.match(r"([-+*]|\d+[.)])\s", line):
1293
+ cell_lines.append(line)
1294
+ new_line = False
953
1295
  else:
954
- doc = self.doc
1296
+ cell_lines[-1] += f" {line}"
1297
+ # an unescaped `|` would end the cell, also inside a code span
1298
+ return re.sub(r"(?<!\\)\|", r"\\|", "<br>".join(cell_lines))
955
1299
 
956
- if doc is not None:
957
- if modify_doc_handler is not None:
958
- doc = modify_doc_handler(doc)
959
- result += doc
1300
+ def _get_argument_table(
1301
+ self,
1302
+ arguments: List[ArgumentInfo],
1303
+ link_resolver: Optional[LinkResolver] = None,
1304
+ targets: Optional[Mapping[str, ReferenceTarget]] = None,
1305
+ with_descriptions: bool = False,
1306
+ ) -> str:
1307
+ """The arguments as a table; with descriptions, they get a fifth column."""
1308
+ result = "\n| | | | | |" if with_descriptions else "\n| | | | |"
1309
+ result += "\n|:--|:--|:--|:--|:--|" if with_descriptions else "\n|:--|:--|:--|:--|"
1310
+
1311
+ escaped_pipe = " \\| "
1312
+
1313
+ def row(
1314
+ name: str,
1315
+ types: Sequence[str],
1316
+ type_docs: Optional[Mapping[str, str]],
1317
+ default_value: Optional[Any],
1318
+ description: str,
1319
+ ) -> str:
1320
+ type_cell = escaped_pipe.join(_type_markdown(s, type_docs, link_resolver, True) for s in types)
1321
+ cells = (
1322
+ f"\n| `{name}`"
1323
+ f"| {': ' if types else ' '}"
1324
+ f"{type_cell} "
1325
+ f"| {'=' if default_value is not None else ''} "
1326
+ f"| {f'`{default_value!s}`' if default_value else ''} |"
1327
+ )
1328
+ return f"{cells} {description} |" if with_descriptions else cells
960
1329
 
1330
+ for a in arguments:
1331
+ description = self._description_cell(a.doc, link_resolver, targets) if with_descriptions and a.doc else ""
1332
+ result += row(
1333
+ f"{self._get_argument_prefix(a)}{a.name!s}", a.types or (), a.type_docs, a.default_value, description
1334
+ )
1335
+ if with_descriptions:
1336
+ # names the documentation describes without being arguments, like ones taken by `**kwargs`
1337
+ for name, doc in self.extra_argument_docs or []:
1338
+ result += row(name, (), None, None, self._description_cell(doc, link_resolver, targets))
961
1339
  return result
962
1340
 
963
- def _get_signature(self, header_level: int, add_type: bool = True) -> str:
1341
+ def _get_signature(
1342
+ self,
1343
+ header_level: int,
1344
+ add_type: bool = True,
1345
+ link_resolver: Optional[LinkResolver] = None,
1346
+ targets: Optional[Mapping[str, ReferenceTarget]] = None,
1347
+ ) -> str:
964
1348
  if add_type:
965
1349
  result = (
966
1350
  f"#{'#' * header_level} "
@@ -968,50 +1352,46 @@ class KeywordDoc(SourceEntity):
968
1352
  )
969
1353
  else:
970
1354
  if not self.is_initializer:
971
- result = f"\n\n#{'#' * header_level} {self.name}\n"
1355
+ result = f"\n\n#{'#' * header_level} {_heading_name(self.name)}\n"
972
1356
  else:
973
1357
  result = ""
974
1358
 
975
- if self.arguments:
976
- result += f"\n##{'#' * header_level} Arguments: \n"
1359
+ arguments = [
1360
+ a
1361
+ for a in self.arguments
1362
+ if a.kind not in [KeywordArgumentKind.NAMED_ONLY_MARKER, KeywordArgumentKind.POSITIONAL_ONLY_MARKER]
1363
+ ]
1364
+ has_descriptions = any(a.doc for a in arguments) or bool(self.extra_argument_docs)
977
1365
 
978
- result += "\n| | | | |"
979
- result += "\n|:--|:--|:--|:--|"
1366
+ if self.arguments or has_descriptions:
1367
+ result += f"\n##{'#' * header_level} Arguments: \n"
980
1368
 
981
- escaped_pipe = " \\| "
1369
+ result += self._get_argument_table(arguments, link_resolver, targets, with_descriptions=has_descriptions)
982
1370
 
983
- for a in self.arguments:
984
- prefix = ""
985
- if a.kind in [
986
- KeywordArgumentKind.NAMED_ONLY_MARKER,
987
- KeywordArgumentKind.POSITIONAL_ONLY_MARKER,
988
- ]:
989
- continue
990
-
991
- if a.kind == KeywordArgumentKind.VAR_POSITIONAL:
992
- prefix = "*"
993
- elif a.kind == KeywordArgumentKind.VAR_NAMED:
994
- prefix = "**"
995
- elif a.kind == KeywordArgumentKind.NAMED_ONLY:
996
- prefix = "🏷"
997
- elif a.kind == KeywordArgumentKind.POSITIONAL_ONLY:
998
- prefix = "⟶"
999
-
1000
- def escape_pipe(s: str) -> str:
1001
- return s.replace("|", "\\|")
1002
-
1003
- result += (
1004
- f"\n| `{prefix}{a.name!s}`"
1005
- f"| {': ' if a.types else ' '}"
1006
- f"{escaped_pipe.join(f'`{escape_pipe(s)}`' for s in a.types) if a.types else ''} "
1007
- f"| {'=' if a.default_value is not None else ''} "
1008
- f"| {f'`{a.default_value!s}`' if a.default_value else ''} |"
1009
- )
1010
1371
  if self.return_type:
1011
1372
  if result:
1012
1373
  result += "\n\n"
1013
1374
 
1014
- result += f"**Return Type**: `{self.return_type}`\n"
1375
+ result += (
1376
+ f"**Return Type**: {_type_markdown(self.return_type, self.return_type_docs, link_resolver, False)}"
1377
+ )
1378
+ if self.return_doc:
1379
+ result += f" — {self._format_description(self.return_doc, link_resolver, targets)}"
1380
+ result += "\n"
1381
+ elif self.return_doc:
1382
+ if result:
1383
+ result += "\n\n"
1384
+
1385
+ result += f"**Returns**: {self._format_description(self.return_doc, link_resolver, targets)}\n"
1386
+
1387
+ if self.raises:
1388
+ if result:
1389
+ result += "\n\n"
1390
+
1391
+ result += "**Raises**: "
1392
+ for name, description in self.raises:
1393
+ result += f"\n- `{name}`: {self._format_description(description, link_resolver, targets)}"
1394
+ result += "\n"
1015
1395
 
1016
1396
  if self.tags:
1017
1397
  if result:
@@ -1279,6 +1659,7 @@ class LibraryDoc:
1279
1659
  stdout: Optional[str] = field(default=None, compare=False)
1280
1660
  has_listener: Optional[bool] = None
1281
1661
  library_type: Optional[LibraryType] = None
1662
+ loaded_without_arguments: bool = False
1282
1663
  _source_id: Optional[FileId] = field(default=None, init=False, compare=False, hash=False, repr=False)
1283
1664
  _hash_value: int = field(default=0, init=False, compare=False, hash=False, repr=False)
1284
1665
  _stable_id: str = field(default="", init=False, compare=False, hash=False, repr=False)
@@ -1412,6 +1793,66 @@ class LibraryDoc:
1412
1793
 
1413
1794
  return [t for t in self.types if alias(t.name) in type_names]
1414
1795
 
1796
+ def get_types_for_argument(self, argument: ArgumentInfo) -> List[TypeDoc]:
1797
+ """The type documentation of the types of an argument.
1798
+
1799
+ The names of the used types and of their documentation differ for type
1800
+ aliases and for standard types such as `int` (`integer`), so the mapping
1801
+ Libdoc computed is used when it exists.
1802
+ """
1803
+ if argument.type_docs:
1804
+ names = set(argument.type_docs.values())
1805
+ return [t for t in self.types if t.name in names]
1806
+
1807
+ return self.get_types(argument.types)
1808
+
1809
+ def get_reference_targets(self) -> Dict[str, ReferenceTarget]:
1810
+ """What reference links (`[Name]`) in Markdown documentation and names in
1811
+ backticks in Robot Framework's format of this library can point to.
1812
+
1813
+ The same targets in the same order of precedence as in Libdoc: the default
1814
+ sections, keywords and their types, then headings and reference
1815
+ definitions of the introduction.
1816
+ """
1817
+ targets: Dict[str, ReferenceTarget] = {}
1818
+
1819
+ def add(reference: str, kind: str, name: str, url: Optional[str] = None) -> None:
1820
+ targets[normalize_reference(reference)] = ReferenceTarget(kind, name, url)
1821
+
1822
+ for reference, section in (
1823
+ ("introduction", "Introduction"),
1824
+ ("library introduction", "Introduction"),
1825
+ ("importing", "Importing"),
1826
+ ("library importing", "Importing"),
1827
+ ("keywords", "Keywords"),
1828
+ ):
1829
+ add(reference, REFERENCE_SECTION, section)
1830
+
1831
+ for type_doc in self.types:
1832
+ add(type_doc.name, REFERENCE_TYPE, type_doc.name)
1833
+ for kw in self.keywords.keywords:
1834
+ add(kw.name, REFERENCE_KEYWORD, kw.name)
1835
+ for type_docs in (*(a.type_docs for a in kw.arguments), kw.return_type_docs):
1836
+ for used_name, type_doc_name in (type_docs or {}).items():
1837
+ add(used_name, REFERENCE_TYPE, type_doc_name)
1838
+
1839
+ if self.doc and self.doc_format == MARKDOWN_DOC_FORMAT:
1840
+ for reference, url in extract_reference_definitions(self.doc).items():
1841
+ targets[reference] = ReferenceTarget(REFERENCE_LINK, reference, url)
1842
+ for title in self.get_introduction_headings():
1843
+ add(title, REFERENCE_SECTION, title)
1844
+
1845
+ return targets
1846
+
1847
+ def get_introduction_headings(self) -> List[str]:
1848
+ """The titles of the headings of the introduction that references can name."""
1849
+ if self.doc and self.doc_format == MARKDOWN_DOC_FORMAT:
1850
+ return [title for _, title in iter_headings(self.doc)]
1851
+ if self.doc and self.doc_format == ROBOT_DOC_FORMAT:
1852
+ headers = RobotHeaderFormatter()
1853
+ return [match.group(2) for line in self.doc.splitlines() if (match := headers.match(line.strip()))]
1854
+ return []
1855
+
1415
1856
  @property
1416
1857
  def is_deprecated(self) -> bool:
1417
1858
  return DEPRECATED_PATTERN.match(self.doc) is not None
@@ -1437,52 +1878,237 @@ class LibraryDoc:
1437
1878
  add_signature: bool = True,
1438
1879
  only_doc: bool = True,
1439
1880
  header_level: int = 2,
1881
+ *,
1882
+ link_resolver: Optional[LinkResolver] = None,
1440
1883
  ) -> str:
1884
+ if not only_doc:
1885
+ return self._page_to_markdown(header_level, link_resolver)
1886
+
1441
1887
  with io.StringIO(newline="\n") as result:
1442
1888
 
1443
1889
  def write_lines(*args: str) -> None:
1444
1890
  result.writelines(i + "\n" for i in args)
1445
1891
 
1446
- if add_signature and any(v for v in self.inits.values() if v.arguments):
1447
- for i in self.inits.values():
1448
- write_lines(i.to_markdown(header_level=header_level), "", "---")
1449
-
1450
- write_lines(
1451
- f"#{'#' * header_level} {(self.type.capitalize()) if self.type else 'Unknown'} *{self.name}*",
1452
- "",
1892
+ # with a link resolver, the names of every format link, as on the full page
1893
+ targets = (
1894
+ self.get_reference_targets()
1895
+ if link_resolver is not None or self.doc_format == MARKDOWN_DOC_FORMAT
1896
+ else None
1453
1897
  )
1454
1898
 
1455
- if self.version or self.scope:
1456
- write_lines("| | |", "| :--- | :--- |")
1457
-
1458
- if self.version:
1459
- write_lines(f"| **Library Version:** | {self.version} |")
1460
- if self.scope:
1461
- write_lines(f"| **Library Scope:** | {self.scope} |")
1899
+ if add_signature and any(v for v in self.inits.values() if v.arguments):
1900
+ for i in self.inits.values():
1901
+ init_markdown = i.to_markdown(
1902
+ header_level=header_level, link_resolver=link_resolver, reference_targets=targets
1903
+ )
1904
+ write_lines(init_markdown, "", "---")
1462
1905
 
1463
- write_lines("", "")
1906
+ result.write(self._get_title_markdown(header_level))
1464
1907
 
1465
1908
  if self.doc:
1466
1909
  write_lines(f"##{'#' * header_level} Introduction", "")
1467
1910
 
1468
1911
  if self.doc_format == ROBOT_DOC_FORMAT:
1469
- doc = MarkDownFormatter().format(self.doc)
1470
-
1471
- if "%TOC%" in doc:
1472
- doc = self._add_toc(doc, only_doc)
1473
-
1474
- result.write(doc)
1912
+ doc = MarkDownFormatter(_name_linker(targets, link_resolver)).format(self.doc)
1913
+ result.write(replace_toc(doc, self._get_toc_sections(only_doc)))
1475
1914
 
1476
1915
  elif self.doc_format == REST_DOC_FORMAT:
1477
1916
  result.write(convert_from_rest(self.doc))
1917
+ elif self.doc_format == MARKDOWN_DOC_FORMAT:
1918
+ doc = normalize_markdown_doc(self.doc, targets, link_resolver)
1919
+ result.write(replace_toc(doc, self._get_toc_sections(only_doc)))
1478
1920
  else:
1479
1921
  result.write(self.doc)
1480
1922
 
1481
- if not only_doc:
1482
- result.write(self._get_doc_for_keywords(header_level=header_level))
1923
+ # linking `names` in backticks to headings belongs to the Robot format; with a link resolver,
1924
+ # the names are linked already, and this would link the code of type links once more
1925
+ if self.doc_format == MARKDOWN_DOC_FORMAT or link_resolver is not None:
1926
+ return result.getvalue()
1483
1927
 
1484
1928
  return self._link_inline_links(result.getvalue())
1485
1929
 
1930
+ def _get_title_markdown(self, header_level: int) -> str:
1931
+ result = f"#{'#' * header_level} {(self.type.capitalize()) if self.type else 'Unknown'} *{self.name}*\n\n"
1932
+
1933
+ if self.version or self.scope:
1934
+ result += "| | |\n| :--- | :--- |\n"
1935
+
1936
+ if self.version:
1937
+ result += f"| **Library Version:** | {self.version} |\n"
1938
+ if self.scope:
1939
+ result += f"| **Library Scope:** | {self.scope} |\n"
1940
+
1941
+ result += "\n\n"
1942
+
1943
+ return result
1944
+
1945
+ def get_page_keywords(self) -> List[KeywordDoc]:
1946
+ """The keywords of the full page: ordered by name as Libdoc orders them, private keywords left out."""
1947
+ return sorted(
1948
+ (kw for kw in self.keywords.values() if not kw.is_private), key=lambda kw: (kw.name.lower(), kw.name)
1949
+ )
1950
+
1951
+ def get_page_types(self) -> List[TypeDoc]:
1952
+ """The data types of the full page, ordered by name as Libdoc orders them."""
1953
+ return sorted(self.types, key=lambda t: (t.name.lower(), t.name))
1954
+
1955
+ def get_page_anchors(self, page: str, header_level: int = 0) -> Tuple[List[str], Dict[str, str]]:
1956
+ """The anchors of the keyword headings of a full page, in the order of
1957
+ `get_page_keywords`, and of its type headings, by type name.
1958
+
1959
+ Headings are matched by their title, so other headings in a section do
1960
+ not shift them; a keyword whose heading is missing gets an empty anchor.
1961
+ """
1962
+ keyword_anchors = _match_heading_anchors(
1963
+ section_anchors(page, "Keywords", header_level + 2),
1964
+ # the finished page writes the variables in a name as inline code
1965
+ [{name, code_span_variables(name)} for name in (_heading_name(kw.name) for kw in self.get_page_keywords())],
1966
+ )
1967
+
1968
+ page_types = self.get_page_types()
1969
+ type_anchors = _match_heading_anchors(
1970
+ section_anchors(page, "Data types", header_level + 2),
1971
+ [{f"{type_doc.name} ({type_doc.type})"} for type_doc in page_types],
1972
+ )
1973
+
1974
+ return keyword_anchors, {t.name: anchor for t, anchor in zip(page_types, type_anchors) if anchor}
1975
+
1976
+ def _page_to_markdown(self, header_level: int, link_resolver: Optional[LinkResolver]) -> str:
1977
+ """The full page of `robotcode doc lib`, the REPL's `.doc` and the documentation view."""
1978
+ head, keywords, tail = self._get_page_parts(header_level, link_resolver)
1979
+
1980
+ # Only the assembled page knows its headings: an anchor can carry a number, and a
1981
+ # private keyword or a section the page leaves out has no heading at all.
1982
+ page = head + keywords + tail
1983
+ keyword_anchors: Dict[str, str] = {}
1984
+ for title, anchor in section_anchors(page, "Keywords", header_level + 2):
1985
+ keyword_anchors.setdefault(normalize_reference(_heading_title_name(title)), anchor)
1986
+ # the headings of the introduction win over the page's own sections, as the targets of Libdoc do
1987
+ section_anchors_by_title: Dict[str, str] = {}
1988
+ introduction: Dict[str, str] = {}
1989
+ in_introduction = False
1990
+ for level, title, anchor in heading_anchors(page):
1991
+ if level == header_level + 2:
1992
+ in_introduction = title == "Introduction"
1993
+ section_anchors_by_title.setdefault(normalize_reference(title), anchor)
1994
+ elif level > header_level + 2 and in_introduction:
1995
+ introduction.setdefault(normalize_reference(title), anchor)
1996
+ section_anchors_by_title.update(introduction)
1997
+ _, type_anchors = self.get_page_anchors(page, header_level)
1998
+
1999
+ def resolver(kind: str, name: str) -> Optional[str]:
2000
+ if kind == REFERENCE_TYPE:
2001
+ anchor = type_anchors.get(name)
2002
+ else:
2003
+ link = link_resolver(kind, name) if link_resolver is not None else None
2004
+ if link is None or not link.startswith("#"):
2005
+ return link
2006
+ anchors = keyword_anchors if kind == REFERENCE_KEYWORD else section_anchors_by_title
2007
+ anchor = anchors.get(normalize_reference(name))
2008
+ return f"#{anchor}" if anchor is not None else None
2009
+
2010
+ head, keywords, tail = self._get_page_parts(header_level, resolver)
2011
+
2012
+ page = head + keywords + tail
2013
+ if keywords:
2014
+ index_anchors, _ = self.get_page_anchors(page, header_level)
2015
+ index = "\n".join(
2016
+ f"- [{escape_link_text(kw.name)}](#{anchor})"
2017
+ for kw, anchor in zip(self.get_page_keywords(), index_anchors)
2018
+ if anchor
2019
+ )
2020
+ page = f"{head}{index}\n\n{keywords}{tail}"
2021
+
2022
+ if self.doc_format not in (REST_DOC_FORMAT, HTML_DOC_FORMAT):
2023
+ page = code_span_variables(page)
2024
+
2025
+ return f"{page.rstrip()}\n"
2026
+
2027
+ def _get_page_parts(self, header_level: int, link_resolver: Optional[LinkResolver]) -> Tuple[str, str, str]:
2028
+ """The page up to the keyword entries, the keyword entries, and the rest of the page."""
2029
+ targets = self.get_reference_targets()
2030
+ separator = "\n\n---\n\n"
2031
+ # each documentation on the page keeps the URLs of its own reference definitions
2032
+ labels: Dict[str, str] = {}
2033
+
2034
+ head = self._get_title_markdown(header_level)
2035
+ if self.doc:
2036
+ head += f"##{'#' * header_level} Introduction\n\n"
2037
+ head += unique_reference_labels(
2038
+ self._get_page_introduction(header_level, link_resolver, targets).strip(), labels
2039
+ )
2040
+
2041
+ if any(v for v in self.inits.values() if v.arguments):
2042
+ head = f"{head.rstrip()}{separator}##{'#' * header_level} Importing\n\n"
2043
+ head += separator.join(
2044
+ unique_reference_labels(self._get_page_entry(kw, header_level, link_resolver, targets), labels)
2045
+ for kw in self.inits.values()
2046
+ )
2047
+
2048
+ keywords = ""
2049
+ page_keywords = self.get_page_keywords()
2050
+ if page_keywords:
2051
+ head = f"{head.rstrip()}{separator}##{'#' * header_level} Keywords\n\n"
2052
+ keywords = separator.join(
2053
+ unique_reference_labels(self._get_page_entry(kw, header_level, link_resolver, targets), labels)
2054
+ for kw in page_keywords
2055
+ )
2056
+
2057
+ tail = ""
2058
+ if self.types:
2059
+ if not keywords:
2060
+ head = head.rstrip()
2061
+ tail += f"{separator}##{'#' * header_level} Data types\n\n"
2062
+ tail += separator.join(
2063
+ unique_reference_labels(
2064
+ t.to_markdown(
2065
+ header_level=header_level + 1,
2066
+ link_resolver=link_resolver,
2067
+ reference_targets=targets,
2068
+ # headings in the documentation sit below the type's `Documentation:`
2069
+ modify_doc_handler=_page_heading_shift(t.doc_format, header_level + 3),
2070
+ ).strip(),
2071
+ labels,
2072
+ )
2073
+ for t in self.get_page_types()
2074
+ )
2075
+
2076
+ return head.lstrip(), keywords, tail
2077
+
2078
+ def _get_page_introduction(
2079
+ self, header_level: int, link_resolver: Optional[LinkResolver], targets: Mapping[str, ReferenceTarget]
2080
+ ) -> str:
2081
+ if self.doc_format == ROBOT_DOC_FORMAT:
2082
+ doc = MarkDownFormatter(_name_linker(targets, link_resolver)).format(self.doc)
2083
+ doc = replace_toc(doc, self._get_toc_sections(only_doc=False))
2084
+ elif self.doc_format == REST_DOC_FORMAT:
2085
+ doc = convert_from_rest(self.doc)
2086
+ elif self.doc_format == MARKDOWN_DOC_FORMAT:
2087
+ doc = normalize_markdown_doc(self.doc, targets, link_resolver)
2088
+ doc = replace_toc(doc, self._get_toc_sections(only_doc=False))
2089
+ else:
2090
+ doc = self.doc
2091
+
2092
+ # the headings of the introduction sit below `Introduction`, its table of contents is already built
2093
+ shift = _page_heading_shift(self.doc_format, header_level + 1)
2094
+ return shift(doc) if shift is not None else doc
2095
+
2096
+ @staticmethod
2097
+ def _get_page_entry(
2098
+ kw: KeywordDoc,
2099
+ header_level: int,
2100
+ link_resolver: Optional[LinkResolver],
2101
+ targets: Mapping[str, ReferenceTarget],
2102
+ ) -> str:
2103
+ return kw.to_markdown(
2104
+ header_level=header_level + 2,
2105
+ add_type=False,
2106
+ # headings in the documentation sit below the keyword's `Documentation:`
2107
+ modify_doc_handler=_page_heading_shift(kw.doc_format, header_level + 3),
2108
+ link_resolver=link_resolver,
2109
+ reference_targets=targets,
2110
+ ).strip()
2111
+
1486
2112
  @property
1487
2113
  def source_or_origin(self) -> Optional[str]:
1488
2114
  if self.source is not None:
@@ -1504,56 +2130,22 @@ class LibraryDoc:
1504
2130
 
1505
2131
  def repl(m: re.Match) -> str: # type: ignore
1506
2132
  if m.group(2) in headers:
1507
- return f"[{m.group(2)!s}](\\#{str(m.group(2)).lower().replace(' ', '-')})"
2133
+ return f"[{m.group(2)!s}](#{slugify(str(m.group(2)))})"
1508
2134
  return str(m.group(0))
1509
2135
 
1510
2136
  return str(RE_INLINE_LINK.sub(repl, text))
1511
2137
 
1512
- def _get_doc_for_keywords(self, header_level: int = 2) -> str:
1513
- result = ""
1514
- if any(v for v in self.inits.values() if v.arguments):
1515
- result += "\n---\n\n"
1516
- result += f"\n##{'#' * header_level} Importing\n\n"
1517
-
1518
- first = True
1519
-
1520
- for kw in self.inits.values():
1521
- if not first:
1522
- result += "\n---\n"
1523
- first = False
1524
-
1525
- result += "\n" + kw.to_markdown(add_type=False)
1526
-
1527
- if self.keywords:
1528
- result += "\n---\n\n"
1529
- result += f"\n##{'#' * header_level} Keywords\n\n"
1530
-
1531
- first = True
1532
-
1533
- for kw in self.keywords.values():
1534
- if not first:
1535
- result += "\n---\n"
1536
- first = False
1537
-
1538
- result += "\n" + kw.to_markdown(header_level=header_level, add_type=False)
1539
- return result
1540
-
1541
- def _add_toc(self, doc: str, only_doc: bool = True) -> str:
1542
- toc = self._create_toc(doc, only_doc)
1543
- return "\n".join(line if line.strip() != "%TOC%" else toc for line in doc.splitlines())
1544
-
1545
- def _create_toc(self, doc: str, only_doc: bool = True) -> str:
1546
- entries = re.findall(r"^##\s+(.+)", doc, flags=re.MULTILINE)
1547
-
2138
+ def _get_toc_sections(self, only_doc: bool = True) -> List[str]:
2139
+ """The sections a full rendering has besides the ones of the introduction."""
2140
+ entries: List[str] = []
1548
2141
  if not only_doc:
1549
2142
  if any(v for v in self.inits.values() if v.arguments):
1550
2143
  entries.append("Importing")
1551
- if self.keywords:
2144
+ if self.get_page_keywords():
1552
2145
  entries.append("Keywords")
1553
- # TODO if self.data_types:
1554
- # entries.append("Data types")
1555
-
1556
- return "\n".join(f"- [{entry}](#{entry.lower().replace(' ', '-')})" for entry in entries)
2146
+ if self.types:
2147
+ entries.append("Data types")
2148
+ return entries
1557
2149
 
1558
2150
 
1559
2151
  def var_repr(value: Any) -> str:
@@ -1593,8 +2185,12 @@ class VariablesDoc(LibraryDoc):
1593
2185
  add_signature: bool = True,
1594
2186
  only_doc: bool = True,
1595
2187
  header_level: int = 2,
2188
+ *,
2189
+ link_resolver: Optional[LinkResolver] = None,
1596
2190
  ) -> str:
1597
- result = super(VariablesDoc, self).to_markdown(add_signature, only_doc, header_level)
2191
+ result = super(VariablesDoc, self).to_markdown(
2192
+ add_signature, only_doc, header_level, link_resolver=link_resolver
2193
+ )
1598
2194
 
1599
2195
  if self.variables:
1600
2196
  result += "\n---\n\n"
@@ -1770,6 +2366,71 @@ class KeywordWrapper:
1770
2366
  return None
1771
2367
 
1772
2368
 
2369
+ class DocstringInfo(NamedTuple):
2370
+ """What a keyword documentation consists of.
2371
+
2372
+ The Google-style sections (`Args:`, `Returns:`, `Raises:`) only exist with
2373
+ Robot Framework 7.5 or newer, older versions leave them in the text.
2374
+ """
2375
+
2376
+ doc: str
2377
+ tags: List[str]
2378
+ argument_docs: Optional[Dict[str, str]] = None
2379
+ return_doc: str = ""
2380
+ raises: Optional[List[Tuple[str, str]]] = None
2381
+
2382
+
2383
+ if RF_VERSION >= (7, 5):
2384
+
2385
+ def get_docstring_info(kw_doc: Any, kw: Any, is_resource: bool) -> DocstringInfo:
2386
+ """Return documentation text, tags and documentation sections of a keyword.
2387
+
2388
+ Robot Framework 7.5 no longer splits the `Tags:` section off and no
2389
+ longer unescapes resource keyword documentation in `KeywordDocBuilder`;
2390
+ `update_docs()` does it, but it mutates the keyword, which may belong to
2391
+ a running session. So the documentation is parsed here instead.
2392
+ """
2393
+ text = kw.doc or ""
2394
+ if is_resource:
2395
+ text = unescape(text)
2396
+
2397
+ # a `Tags:` line without a preceding empty row is reported as a warning
2398
+ with LOGGER.cache_only:
2399
+ info = parse_docstring(text, kw_doc.name)
2400
+
2401
+ tags = RobotTags(kw_doc.tags)
2402
+ tags.add(info.tags, remove_negated=is_resource)
2403
+
2404
+ return DocstringInfo(
2405
+ doc=kw_doc.doc if kw.error else info.doc,
2406
+ tags=list(tags),
2407
+ argument_docs=dict(info.args) or None,
2408
+ return_doc=info.returns,
2409
+ raises=list(info.raises.items()) or None,
2410
+ )
2411
+
2412
+ else:
2413
+
2414
+ def get_docstring_info(kw_doc: Any, kw: Any, is_resource: bool) -> DocstringInfo:
2415
+ return DocstringInfo(doc=kw_doc.doc, tags=list(kw_doc.tags))
2416
+
2417
+
2418
+ def _get_arguments(kw_doc: Any, info: Optional[DocstringInfo]) -> List[ArgumentInfo]:
2419
+ arguments = [ArgumentInfo.from_robot(a) for a in kw_doc.args]
2420
+ if info is not None and info.argument_docs:
2421
+ for argument in arguments:
2422
+ argument.doc = info.argument_docs.get(argument.name, "")
2423
+ return arguments
2424
+
2425
+
2426
+ def _get_extra_argument_docs(kw_doc: Any, info: Optional[DocstringInfo]) -> Optional[List[Tuple[str, str]]]:
2427
+ # Libdoc fails a keyword that documents an argument it does not have, the documentation is kept here
2428
+ if info is None or not info.argument_docs:
2429
+ return None
2430
+ names = {a.name for a in kw_doc.args}
2431
+ return [(name, doc) for name, doc in info.argument_docs.items() if name not in names] or None
2432
+
2433
+
1773
2434
  class MessageAndTraceback(NamedTuple):
1774
2435
  message: str
1775
2436
  traceback: List[SourceAndLineInfo]
@@ -2032,6 +2693,10 @@ def get_robot_library_html_doc_str(
2032
2693
  ) -> str:
2033
2694
  _update_env(working_dir)
2034
2695
 
2696
+ if Path(name).suffix.lower() in MARKDOWN_EXTENSIONS:
2697
+ # Robot Framework imports Markdown resource files since 7.5, but its Libdoc rejects them
2698
+ raise DataError("Libdoc does not support Markdown resource files.")
2699
+
2035
2700
  if Path(name).suffix.lower() in ALLOWED_RESOURCE_FILE_EXTENSIONS:
2036
2701
  name = find_file(name, working_dir, base_dir)
2037
2702
  elif Path(name).suffix.lower() in ALLOWED_LIBRARY_FILE_EXTENSIONS:
@@ -2172,6 +2837,7 @@ def get_library_doc(
2172
2837
  library_name = library_name_path.stem
2173
2838
 
2174
2839
  lib = None
2840
+ loaded_without_arguments = False
2175
2841
  try:
2176
2842
  lib = _get_test_library(
2177
2843
  libcode,
@@ -2208,6 +2874,7 @@ def get_library_doc(
2208
2874
  _ = lib.get_instance()
2209
2875
  else:
2210
2876
  _ = lib.instance
2877
+ loaded_without_arguments = True
2211
2878
  except (SystemExit, KeyboardInterrupt):
2212
2879
  raise
2213
2880
  except BaseException:
@@ -2221,12 +2888,25 @@ def get_library_doc(
2221
2888
  create_keywords=True,
2222
2889
  errors=errors,
2223
2890
  )
2891
+ libdoc.loaded_without_arguments = loaded_without_arguments
2224
2892
 
2225
2893
  libdoc.stdout = std_capturer.getvalue()
2226
2894
 
2227
2895
  return libdoc
2228
2896
 
2229
2897
 
2898
+ if RF_VERSION >= (7, 0):
2899
+
2900
+ def _get_scope_name(lib: Any) -> str:
2901
+ # the scope is an enum since RF 7.0, Libdoc shows its name
2902
+ return str(lib.scope.name)
2903
+
2904
+ else:
2905
+
2906
+ def _get_scope_name(lib: Any) -> str:
2907
+ return str(lib.scope)
2908
+
2909
+
2230
2910
  def get_library_doc_from_library(
2231
2911
  lib: Any,
2232
2912
  name: str,
@@ -2263,7 +2943,7 @@ def get_library_doc_from_library(
2263
2943
  source=real_source,
2264
2944
  line_no=lib.lineno if lib is not None else -1,
2265
2945
  version=str(lib.version) if lib is not None else "",
2266
- scope=str(lib.scope) if lib is not None else ROBOT_DEFAULT_SCOPE,
2946
+ scope=_get_scope_name(lib) if lib is not None else ROBOT_DEFAULT_SCOPE,
2267
2947
  doc_format=(str(lib.doc_format) or ROBOT_DOC_FORMAT) if lib is not None else ROBOT_DOC_FORMAT,
2268
2948
  module_spec=(
2269
2949
  module_spec
@@ -2325,15 +3005,21 @@ def get_library_doc_from_library(
2325
3005
 
2326
3006
  kw_source: str = source if source is not None else str(lib.source)
2327
3007
  init_wrappers = [KeywordWrapper(lib.init, kw_source)]
2328
- init_keywords = [(KeywordDocBuilder().build_keyword(k), k) for k in init_wrappers]
3008
+ init_keywords = [
3009
+ (kw_doc, k, _get(lambda: get_docstring_info(kw_doc, k, False)))
3010
+ for kw_doc, k in [(KeywordDocBuilder().build_keyword(k), k) for k in init_wrappers]
3011
+ ]
2329
3012
  libdoc._set_inits(
2330
3013
  KeywordStore(
2331
3014
  keywords=[
2332
3015
  KeywordDoc(
2333
3016
  name=libdoc.name,
2334
- arguments=_get(lambda: [ArgumentInfo.from_robot(a) for a in kw[0].args]) or [],
2335
- doc=_get(lambda: kw[0].doc) or "",
2336
- tags=_get(lambda: list(kw[0].tags)) or [],
3017
+ arguments=_get(lambda: _get_arguments(kw[0], kw[2])) or [],
3018
+ doc=(kw[2].doc if kw[2] is not None else None) or "",
3019
+ tags=(kw[2].tags if kw[2] is not None else None) or [],
3020
+ return_doc=(kw[2].return_doc if kw[2] is not None else None) or "",
3021
+ raises=kw[2].raises if kw[2] is not None else None,
3022
+ extra_argument_docs=_get(lambda: _get_extra_argument_docs(kw[0], kw[2])),
2337
3023
  source=_get(lambda: kw[0].source) or "",
2338
3024
  line_no=kw[0].lineno if kw[0].lineno is not None else -1,
2339
3025
  col_offset=-1,
@@ -2389,7 +3075,10 @@ def get_library_doc_from_library(
2389
3075
 
2390
3076
  return result
2391
3077
 
2392
- keyword_docs = [(KeywordDocBuilder().build_keyword(k), k) for k in keyword_wrappers]
3078
+ keyword_docs = [
3079
+ (kw_doc, k, _get(lambda: get_docstring_info(kw_doc, k, False)))
3080
+ for kw_doc, k in [(KeywordDocBuilder().build_keyword(k), k) for k in keyword_wrappers]
3081
+ ]
2393
3082
  libdoc._set_keywords(
2394
3083
  KeywordStore(
2395
3084
  source=libdoc.name,
@@ -2397,9 +3086,12 @@ def get_library_doc_from_library(
2397
3086
  keywords=[
2398
3087
  KeywordDoc(
2399
3088
  name=kw[0].name,
2400
- arguments=_get(lambda: [ArgumentInfo.from_robot(a) for a in kw[0].args]) or [],
2401
- doc=_get(lambda: kw[0].doc) or "",
2402
- tags=_get(lambda: list(kw[0].tags)) or [],
3089
+ arguments=_get(lambda: _get_arguments(kw[0], kw[2])) or [],
3090
+ doc=(kw[2].doc if kw[2] is not None else None) or "",
3091
+ tags=(kw[2].tags if kw[2] is not None else None) or [],
3092
+ return_doc=(kw[2].return_doc if kw[2] is not None else None) or "",
3093
+ raises=kw[2].raises if kw[2] is not None else None,
3094
+ extra_argument_docs=_get(lambda: _get_extra_argument_docs(kw[0], kw[2])),
2403
3095
  source=_get(lambda: kw[0].source) or "",
2404
3096
  line_no=kw[0].lineno if kw[0].lineno is not None else -1,
2405
3097
  col_offset=-1,
@@ -2425,12 +3117,8 @@ def get_library_doc_from_library(
2425
3117
  ),
2426
3118
  return_type=_get(
2427
3119
  lambda: (
2428
- (
2429
- str(kw[1].args.return_type)
2430
- if kw[1].args.return_type is not None
2431
- and kw[1].args.return_type is not type(None)
2432
- else None
2433
- )
3120
+ # unset is `None` up to RF 7.4 and a falsy `TypeInfo` since RF 7.5
3121
+ (str(kw[1].args.return_type) if kw[1].args.return_type else None)
2434
3122
  if RF_VERSION >= (7, 0)
2435
3123
  else None
2436
3124
  )
@@ -2446,27 +3134,39 @@ def get_library_doc_from_library(
2446
3134
  def _yield_type_info(info: TypeInfo) -> Iterable[TypeInfo]:
2447
3135
  if not info.is_union:
2448
3136
  yield info
3137
+ # the nested types of a recursive type alias (RF >= 7.5) are not `TypeInfo`s
3138
+ if RF_VERSION >= (7, 5) and info.is_recursive:
3139
+ return
2449
3140
  if info.nested and info.type is not Literal:
2450
3141
  for nested in info.nested:
2451
3142
  yield from _yield_type_info(nested)
2452
3143
 
3144
+ def _yield_names_and_type_infos(args: Any) -> Iterable[Tuple[str, TypeInfo]]:
3145
+ for arg in args:
3146
+ for type_info in _yield_type_info(arg.type):
3147
+ yield arg.name, type_info
3148
+ # as Libdoc: the types of the return value are documented under the name `return`
3149
+ if RF_VERSION >= (7, 0) and args.return_type:
3150
+ for type_info in _yield_type_info(args.return_type):
3151
+ yield "return", type_info
3152
+
2453
3153
  def _get_type_docs(keywords: List[Any], custom_converters: List[Any]) -> Set[RobotTypeDoc]:
2454
3154
  type_docs: Dict[RobotTypeDoc, Set[str]] = {}
2455
3155
  for kw in keywords:
2456
3156
  for arg in kw.args:
2457
3157
  kw.type_docs[arg.name] = {}
2458
- for type_info in _yield_type_info(arg.type):
2459
- if type_info.type is not None:
2460
- if RF_VERSION < (7, 0):
2461
- type_doc = RobotTypeDoc.for_type(
2462
- type_info.type,
2463
- custom_converters,
2464
- )
2465
- else:
2466
- type_doc = RobotTypeDoc.for_type(type_info, custom_converters)
2467
- if type_doc:
2468
- kw.type_docs[arg.name][type_info.name] = type_doc.name
2469
- type_docs.setdefault(type_doc, set()).add(kw.name)
3158
+ for name, type_info in _yield_names_and_type_infos(kw.args):
3159
+ if type_info.type is None:
3160
+ continue
3161
+ if RF_VERSION < (7, 0):
3162
+ type_doc = RobotTypeDoc.for_type(type_info.type, custom_converters)
3163
+ elif RF_VERSION < (7, 5):
3164
+ type_doc = RobotTypeDoc.for_type(type_info, custom_converters)
3165
+ else:
3166
+ type_doc = RobotTypeDoc.for_type(type_info, custom_converters, libdoc.doc_format)
3167
+ if type_doc:
3168
+ kw.type_docs.setdefault(name, {})[type_info.name] = type_doc.name
3169
+ type_docs.setdefault(type_doc, set()).add(kw.name)
2470
3170
  for type_doc, usages in type_docs.items():
2471
3171
  type_doc.usages = sorted(usages, key=str.lower)
2472
3172
  return set(type_docs)
@@ -2491,6 +3191,12 @@ def get_library_doc_from_library(
2491
3191
  )
2492
3192
  ]
2493
3193
 
3194
+ for robot_kw_docs, store in ((keyword_docs, libdoc.keywords), (init_keywords, libdoc.inits)):
3195
+ for (robot_kw_doc, _, _), kw_doc in zip(robot_kw_docs, store.keywords):
3196
+ for argument in kw_doc.arguments:
3197
+ argument.type_docs = dict(robot_kw_doc.type_docs.get(argument.name) or {}) or None
3198
+ kw_doc.return_type_docs = dict(robot_kw_doc.type_docs.get("return") or {}) or None
3199
+
2494
3200
  except (SystemExit, KeyboardInterrupt):
2495
3201
  raise
2496
3202
  except BaseException as e:
@@ -3354,7 +4060,7 @@ def _build_resource_doc(
3354
4060
 
3355
4061
  libdoc = ResourceDoc(
3356
4062
  name=lib.name or "",
3357
- doc=lib.doc,
4063
+ doc=unescape(lib.doc) if lib.doc else lib.doc,
3358
4064
  source=source,
3359
4065
  line_no=1,
3360
4066
  resource_imports=resource_imports if resource_imports is not None else [],
@@ -3368,9 +4074,12 @@ def _build_resource_doc(
3368
4074
  keywords=[
3369
4075
  KeywordDoc(
3370
4076
  name=kw[0].name,
3371
- arguments=[ArgumentInfo.from_robot(a) for a in kw[0].args],
3372
- doc=kw[0].doc,
3373
- tags=list(kw[0].tags),
4077
+ arguments=_get_arguments(kw[0], kw[2]),
4078
+ doc=kw[2].doc,
4079
+ tags=kw[2].tags,
4080
+ return_doc=kw[2].return_doc,
4081
+ raises=kw[2].raises,
4082
+ extra_argument_docs=_get_extra_argument_docs(kw[0], kw[2]),
3374
4083
  source=str(kw[0].source),
3375
4084
  name_token=_get_keyword_name_token_from_line(keyword_name_nodes, kw[0].lineno),
3376
4085
  line_no=kw[0].lineno if kw[0].lineno is not None else -1,
@@ -3391,8 +4100,11 @@ def _build_resource_doc(
3391
4100
  argument_definitions=_get_argument_definitions_from_line(keywords_nodes, source, kw[0].lineno),
3392
4101
  )
3393
4102
  for kw in [
3394
- (KeywordDocBuilder(resource=True).build_keyword(lw), lw)
3395
- for lw in (lib.handlers if RF_VERSION < (7, 0) else lib.keywords)
4103
+ (kw_doc, lw, get_docstring_info(kw_doc, lw, True))
4104
+ for kw_doc, lw in [
4105
+ (KeywordDocBuilder(resource=True).build_keyword(lw), lw)
4106
+ for lw in (lib.handlers if RF_VERSION < (7, 0) else lib.keywords)
4107
+ ]
3396
4108
  ]
3397
4109
  ],
3398
4110
  )