Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make RST docs consistent with Editor Help docs #80690

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 31 additions & 16 deletions doc/tools/make_rst.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@
"This method doesn't need an instance to be called, so it can be called directly using the class name.",
"This method describes a valid operator to use with this type as left-hand operand.",
"This value is an integer composed as a bitmask of the following flags.",
"No return value.",
"There is currently no description for this class. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
"There is currently no description for this signal. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
"There is currently no description for this enum. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
Expand Down Expand Up @@ -454,7 +455,7 @@ def to_rst(self, state: State) -> str:
if self.enum is not None:
return make_enum(self.enum, self.is_bitfield, state)
elif self.type_name == "void":
return "void"
return "|void|"
else:
return make_type(self.type_name, state)

Expand Down Expand Up @@ -1454,14 +1455,26 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:

def make_type(klass: str, state: State) -> str:
if klass.find("*") != -1: # Pointer, ignore
return klass
return f"``{klass}``"

link_type = klass
is_array = False

if link_type.endswith("[]"): # Typed array, strip [] to link to contained type.
link_type = link_type[:-2]
is_array = True

if link_type in state.classes:
return f":ref:`{klass}<class_{link_type}>`"
print_error(f'{state.current_class}.xml: Unresolved type "{klass}".', state)
return klass
type_rst = f":ref:`{link_type}<class_{link_type}>`"
if is_array:
type_rst = f":ref:`Array<class_Array>`\\[{type_rst}\\]"
return type_rst

print_error(f'{state.current_class}.xml: Unresolved type "{link_type}".', state)
type_rst = f"``{link_type}``"
if is_array:
type_rst = f":ref:`Array<class_Array>`\\[{type_rst}\\]"
return type_rst


def make_enum(t: str, is_bitfield: bool, state: State) -> str:
Expand All @@ -1483,7 +1496,7 @@ def make_enum(t: str, is_bitfield: bool, state: State) -> str:
if is_bitfield:
if not state.classes[c].enums[e].is_bitfield:
print_error(f'{state.current_class}.xml: Enum "{t}" is not bitfield.', state)
return f"|bitfield|\\<:ref:`{e}<enum_{c}_{e}>`\\>"
return f"|bitfield|\\[:ref:`{e}<enum_{c}_{e}>`\\]"
else:
return f":ref:`{e}<enum_{c}_{e}>`"

Expand Down Expand Up @@ -1513,36 +1526,36 @@ def make_method_signature(
out += f":ref:`{op_name}<class_{class_def.name}_{ref_type}_{sanitize_operator_name(definition.name, state)}"
for parameter in definition.parameters:
out += f"_{parameter.type_name.type_name}"
out += f">` "
out += f">`"
elif ref_type == "method":
ref_type_qualifier = ""
if definition.name.startswith("_"):
ref_type_qualifier = "private_"
out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type_qualifier}{ref_type}_{definition.name}>` "
out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type_qualifier}{ref_type}_{definition.name}>`"
else:
out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type}_{definition.name}>` "
out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type}_{definition.name}>`"
else:
out += f"**{definition.name}** "
out += f"**{definition.name}**"

out += "**(**"
out += "\\ ("
for i, arg in enumerate(definition.parameters):
if i > 0:
out += ", "
else:
out += " "
out += "\\ "

out += f"{arg.type_name.to_rst(state)} {arg.name}"
out += f"{arg.name}\\: {arg.type_name.to_rst(state)}"

if arg.default_value is not None:
out += f"={arg.default_value}"
out += f" = {arg.default_value}"

if qualifiers is not None and "vararg" in qualifiers:
if len(definition.parameters) > 0:
out += ", ..."
else:
out += " ..."
out += "\\ ..."

out += " **)**"
out += "\\ )"

if qualifiers is not None:
# Use substitutions for abbreviations. This is used to display tooltips on hover.
Expand Down Expand Up @@ -1629,6 +1642,7 @@ def make_footer() -> str:
)
operator_msg = translate("This method describes a valid operator to use with this type as left-hand operand.")
bitfield_msg = translate("This value is an integer composed as a bitmask of the following flags.")
void_msg = translate("No return value.")

return (
f".. |virtual| replace:: :abbr:`virtual ({virtual_msg})`\n"
Expand All @@ -1638,6 +1652,7 @@ def make_footer() -> str:
f".. |static| replace:: :abbr:`static ({static_msg})`\n"
f".. |operator| replace:: :abbr:`operator ({operator_msg})`\n"
f".. |bitfield| replace:: :abbr:`BitField ({bitfield_msg})`\n"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes you really think if BitField should have been called BitFlags (on the outside) all along. "field" for these kinds of properties is rarely ever used. Usually they're referred to as "masks", or "flags".
Question for another time, of course.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the name of the core class. If we ever add such a type to GDScript, it would probably make sense to name it BitField[T] for consistency.

f".. |void| replace:: :abbr:`void ({void_msg})`\n"
)


Expand Down
Loading