asgardius/virtualx-engine
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Make cross-link generation more reliable in RST documentation

Browse source
This commit is contained in:
Yuri Sizov 2022-08-26 19:04:11 +03:00
parent c8ef12a03a
commit a287276ef0
1 changed files with 60 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

121
doc/tools/make_rst.py
View file

@ -878,7 +878,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
f.write("----\n\n") f.write("----\n\n")
if i == 0: if i == 0:
f.write(".. _class_{}_annotation_{}:\n\n".format(class_name, m.name.strip("@"))) f.write(".. _class_{}_annotation_{}:\n\n".format(class_name, m.name))
_, signature = make_method_signature(class_def, m, "", state) _, signature = make_method_signature(class_def, m, "", state)
f.write("- {}\n\n".format(signature)) f.write("- {}\n\n".format(signature))
@ -1337,8 +1337,10 @@ def format_text_block(
# Cross-references to items in this or other class documentation pages. # Cross-references to items in this or other class documentation pages.
elif is_in_tagset(cmd, RESERVED_CROSSLINK_TAGS): elif is_in_tagset(cmd, RESERVED_CROSSLINK_TAGS):
link_type: str = ""
link_target: str = "" link_target: str = ""
if space_pos >= 0: if space_pos >= 0:
link_type = tag_text[:space_pos]
link_target = tag_text[space_pos + 1 :].strip() link_target = tag_text[space_pos + 1 :].strip()
if link_target == "": if link_target == "":
@ -1350,11 +1352,13 @@ def format_text_block(
else: else:
if ( if (
cmd.startswith("method") cmd.startswith("method")
or cmd.startswith("constructor")
or cmd.startswith("operator")
or cmd.startswith("member") or cmd.startswith("member")
or cmd.startswith("signal") or cmd.startswith("signal")
or cmd.startswith("constant")
or cmd.startswith("annotation") or cmd.startswith("annotation")
or cmd.startswith("theme_item") or cmd.startswith("theme_item")
or cmd.startswith("constant")
): ):
if link_target.find(".") != -1: if link_target.find(".") != -1:
ss = link_target.split(".") ss = link_target.split(".")
@ -1371,48 +1375,62 @@ def format_text_block(
class_param = state.current_class class_param = state.current_class
method_param = link_target method_param = link_target
ref_type = "" # Default to the tag command name. This works by default for most tags,
# but member and theme_item have special cases.
ref_type = "_{}".format(link_type)
if link_type == "member":
ref_type = "_property"
if class_param in state.classes: if class_param in state.classes:
class_def = state.classes[class_param] class_def = state.classes[class_param]
if cmd.startswith("constructor"):
if method_param not in class_def.constructors:
print_error(
'{}.xml: Unresolved constructor reference "{}" in {}.'.format(
state.current_class, link_target, context_name
),
state,
)
ref_type = "_constructor"
elif cmd.startswith("method"): if cmd.startswith("method") and method_param not in class_def.methods:
if method_param not in class_def.methods: print_error(
print_error( '{}.xml: Unresolved method reference "{}" in {}.'.format(
'{}.xml: Unresolved method reference "{}" in {}.'.format( state.current_class, link_target, context_name
state.current_class, link_target, context_name ),
), state,
state, )
)
ref_type = "_method"
elif cmd.startswith("operator"): elif cmd.startswith("constructor") and method_param not in class_def.constructors:
if method_param not in class_def.operators: print_error(
print_error( '{}.xml: Unresolved constructor reference "{}" in {}.'.format(
'{}.xml: Unresolved operator reference "{}" in {}.'.format( state.current_class, link_target, context_name
state.current_class, link_target, context_name ),
), state,
state, )
)
ref_type = "_operator"
elif cmd.startswith("member"): elif cmd.startswith("operator") and method_param not in class_def.operators:
if method_param not in class_def.properties: print_error(
print_error( '{}.xml: Unresolved operator reference "{}" in {}.'.format(
'{}.xml: Unresolved member reference "{}" in {}.'.format( state.current_class, link_target, context_name
state.current_class, link_target, context_name ),
), state,
state, )
)
ref_type = "_property" elif cmd.startswith("member") and method_param not in class_def.properties:
print_error(
'{}.xml: Unresolved member reference "{}" in {}.'.format(
state.current_class, link_target, context_name
),
state,
)
elif cmd.startswith("signal") and method_param not in class_def.signals:
print_error(
'{}.xml: Unresolved signal reference "{}" in {}.'.format(
state.current_class, link_target, context_name
),
state,
)
elif cmd.startswith("annotation") and method_param not in class_def.annotations:
print_error(
'{}.xml: Unresolved annotation reference "{}" in {}.'.format(
state.current_class, link_target, context_name
),
state,
)
elif cmd.startswith("theme_item"): elif cmd.startswith("theme_item"):
if method_param not in class_def.theme_items: if method_param not in class_def.theme_items:
@ -1422,27 +1440,9 @@ def format_text_block(
), ),
state, state,
) )
ref_type = "_theme_{}".format(class_def.theme_items[method_param].data_name) else:
# Needs theme data type to be properly linked, which we cannot get without a class.
elif cmd.startswith("signal"): ref_type = "_theme_{}".format(class_def.theme_items[method_param].data_name)
if method_param not in class_def.signals:
print_error(
'{}.xml: Unresolved signal reference "{}" in {}.'.format(
state.current_class, link_target, context_name
),
state,
)
ref_type = "_signal"
elif cmd.startswith("annotation"):
if method_param not in class_def.annotations:
print_error(
'{}.xml: Unresolved annotation reference "{}" in {}.'.format(
state.current_class, link_target, context_name
),
state,
)
ref_type = "_annotation"
elif cmd.startswith("constant"): elif cmd.startswith("constant"):
found = False found = False
@ -1473,7 +1473,6 @@ def format_text_block(
), ),
state, state,
) )
ref_type = "_constant"
else: else:
print_error( print_error(