From 60830fc326e4e58d6637a4ef4d2f5a746136f455 Mon Sep 17 00:00:00 2001 From: Oznogon Date: Wed, 15 Apr 2026 14:40:40 -0700 Subject: [PATCH 1/3] Consolidate function writer logic to a function and emit warnings when a function lacks docs --- script_docs/main.py | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/script_docs/main.py b/script_docs/main.py index ec825c4e6c..0fc1173920 100644 --- a/script_docs/main.py +++ b/script_docs/main.py @@ -12,6 +12,17 @@ def __init__(self, output_filename): self.db.read("api/all.lua") self.output_file = open(output_filename, "wt") + def _write_func(self, data, func): + if not func.doc and not func.example: + print(f"WARNING: {func.name} has no description or example") + out = data + out = out.replace("{{name}}", html.escape(func.name)) + out = out.replace("{{doc}}", html.escape("\n".join(func.doc))) + out = out.replace("{{docs}}", html.escape("\n".join(func.doc))) + out = out.replace("{{example}}", html.escape("\n".join(func.example))) + out = out.replace("{{params}}", html.escape(", ".join(func.params))) + self.output_file.write(out) + def process_block(self, data, tag, params): if tag == "foreach": funcs = list(self.db.filter(params)) @@ -34,24 +45,12 @@ def process_block(self, data, tag, params): for cat in sorted(groups.keys(), key=lambda s: s.lower()): self.output_file.write(f"

{html.escape(cat)} functions

\n") return # Fallback to all functions ungrouped without ToC for func in funcs: - out = data - out = out.replace("{{name}}", html.escape(func.name)) - out = out.replace("{{doc}}", html.escape("\n".join(func.doc))) - out = out.replace("{{docs}}", html.escape("\n".join(func.doc))) - out = out.replace("{{example}}", html.escape("\n".join(func.example))) - out = out.replace("{{params}}", html.escape(", ".join(func.params))) - self.output_file.write(out) + self._write_func(data, func) else: print(tag, params) From d1d0b003f51a449fe6f636b87f71a449baefb6ce Mon Sep 17 00:00:00 2001 From: Oznogon Date: Wed, 15 Apr 2026 14:41:01 -0700 Subject: [PATCH 2/3] Add 1rem separation between functions in script_docs template --- script_docs/template.html | 1 + 1 file changed, 1 insertion(+) diff --git a/script_docs/template.html b/script_docs/template.html index ffc15b7c01..ff68189125 100644 --- a/script_docs/template.html +++ b/script_docs/template.html @@ -67,6 +67,7 @@ font-weight: bold; background: rgba(36, 40, 44, 0.8); padding-left: 1rem; + margin-top: 1rem; border-top: 1px solid rgba(255, 255, 255, 0.1); } From 4312ce1880ebee6a551d541d9ae26722bd8a646a Mon Sep 17 00:00:00 2001 From: Oznogon Date: Wed, 15 Apr 2026 14:41:45 -0700 Subject: [PATCH 3/3] Avoid adding extraneous lines of docs to Entity:setTemplate() --- scripts/api/entity/shiptemplatebasedobject.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/api/entity/shiptemplatebasedobject.lua b/scripts/api/entity/shiptemplatebasedobject.lua index 8808ae18ce..7f60290579 100644 --- a/scripts/api/entity/shiptemplatebasedobject.lua +++ b/scripts/api/entity/shiptemplatebasedobject.lua @@ -1,9 +1,9 @@ local Entity = getLuaEntityFunctionTable() ------ Template-based entity functions ----- +-- Template-based entity functions -- ---- These functions apply to entities created from a ShipTemplate, such as those created by CpuShip(), PlayerSpaceship(), and SpaceStation(). ---- Use setTemplate() to apply a ShipTemplate's properties to an entity. +-- These functions apply to entities created from a ShipTemplate, such as those created by CpuShip(), PlayerSpaceship(), and SpaceStation(). +-- Use setTemplate() to apply a ShipTemplate's properties to an entity. --- Sets this ShipTemplate that defines this entity's traits, and then applies them to this entity. --- ShipTemplates define the entity's class, weapons, hull and shield strength, 3D appearance, and more.