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.
- robotcode/robot/__version__.py +1 -1
- robotcode/robot/config/loader.py +18 -5
- robotcode/robot/config/model.py +258 -61
- robotcode/robot/diagnostics/analyzer_result.py +1 -0
- robotcode/robot/diagnostics/data_cache.py +12 -1
- robotcode/robot/diagnostics/diagnostic_rules.py +75 -0
- robotcode/robot/diagnostics/diagnostics_modifier.py +83 -43
- robotcode/robot/diagnostics/document_cache_helper.py +158 -17
- robotcode/robot/diagnostics/errors.py +7 -0
- robotcode/robot/diagnostics/import_resolver.py +178 -12
- robotcode/robot/diagnostics/imports_manager.py +556 -220
- robotcode/robot/diagnostics/library_doc.py +874 -162
- robotcode/robot/diagnostics/namespace.py +84 -18
- robotcode/robot/diagnostics/namespace_analyzer.py +59 -16
- robotcode/robot/diagnostics/project_index.py +88 -13
- robotcode/robot/diagnostics/scope_tree.py +2 -2
- robotcode/robot/diagnostics/semantic_analyzer/analyzer.py +790 -201
- robotcode/robot/diagnostics/semantic_analyzer/enums.py +39 -2
- robotcode/robot/diagnostics/semantic_analyzer/json_dump.py +364 -0
- robotcode/robot/diagnostics/semantic_analyzer/model.py +72 -11
- robotcode/robot/diagnostics/semantic_analyzer/nodes.py +7 -1
- robotcode/robot/diagnostics/semantic_analyzer/variable_tokenizer.py +218 -112
- robotcode/robot/diagnostics/workspace_config.py +3 -0
- robotcode/robot/utils/markdown_docs.py +733 -0
- robotcode/robot/utils/markdownformatter.py +57 -12
- robotcode/robot/utils/match.py +13 -0
- robotcode/robot/utils/robot_patching.py +4 -0
- robotcode/robot/utils/variables.py +3 -0
- {robotcode_robot-2.6.2.dist-info → robotcode_robot-2.8.0.dev548.dist-info}/METADATA +4 -3
- robotcode_robot-2.8.0.dev548.dist-info/RECORD +48 -0
- {robotcode_robot-2.6.2.dist-info → robotcode_robot-2.8.0.dev548.dist-info}/WHEEL +1 -1
- 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.
|
|
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
|
|
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(
|
|
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
|
-
|
|
594
|
+
doc = MarkDownFormatter().format(self.doc)
|
|
395
595
|
elif self.doc_format == REST_DOC_FORMAT:
|
|
396
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
949
|
-
if
|
|
950
|
-
doc =
|
|
951
|
-
|
|
952
|
-
|
|
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
|
-
|
|
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
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
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(
|
|
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
|
-
|
|
976
|
-
|
|
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
|
-
|
|
979
|
-
result += "\n
|
|
1366
|
+
if self.arguments or has_descriptions:
|
|
1367
|
+
result += f"\n##{'#' * header_level} Arguments: \n"
|
|
980
1368
|
|
|
981
|
-
|
|
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 +=
|
|
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
|
-
|
|
1447
|
-
|
|
1448
|
-
|
|
1449
|
-
|
|
1450
|
-
|
|
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.
|
|
1456
|
-
|
|
1457
|
-
|
|
1458
|
-
|
|
1459
|
-
|
|
1460
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1482
|
-
|
|
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}](
|
|
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
|
|
1513
|
-
|
|
1514
|
-
|
|
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.
|
|
2144
|
+
if self.get_page_keywords():
|
|
1552
2145
|
entries.append("Keywords")
|
|
1553
|
-
|
|
1554
|
-
|
|
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(
|
|
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=
|
|
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 = [
|
|
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:
|
|
2335
|
-
doc=
|
|
2336
|
-
tags=
|
|
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 = [
|
|
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:
|
|
2401
|
-
doc=
|
|
2402
|
-
tags=
|
|
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
|
-
|
|
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
|
-
|
|
2459
|
-
|
|
2460
|
-
|
|
2461
|
-
|
|
2462
|
-
|
|
2463
|
-
|
|
2464
|
-
|
|
2465
|
-
|
|
2466
|
-
|
|
2467
|
-
|
|
2468
|
-
|
|
2469
|
-
|
|
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=
|
|
3372
|
-
doc=kw[
|
|
3373
|
-
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
|
-
(
|
|
3395
|
-
for lw in
|
|
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
|
)
|