From e2f922dd4ac1d877357de3aee2478adf27912dcd Mon Sep 17 00:00:00 2001 From: AGulev Date: Wed, 26 Aug 2026 13:31:48 +0200 Subject: [PATCH] patch v2 docs --- .github/workflows/build_site.yml | 1 + _includes/api_lua_v2.html | 2 +- refdoc.py | 19 ++---- tests/test_api_lua_v2_rendering.rb | 99 ++++++++++++++++++++++++++++++ tests/test_refdoc.py | 88 +++++++++++++++++++++----- 5 files changed, 181 insertions(+), 28 deletions(-) create mode 100644 tests/test_api_lua_v2_rendering.rb diff --git a/.github/workflows/build_site.yml b/.github/workflows/build_site.yml index afb01f9a8..61bd1781a 100644 --- a/.github/workflows/build_site.yml +++ b/.github/workflows/build_site.yml @@ -40,6 +40,7 @@ jobs: - name: Test author profiles, reference docs, and import boundaries run: | bundle exec ruby -I_plugins/defold-author-profiles/lib tests/test_author_profiles.rb + bundle exec ruby tests/test_api_lua_v2_rendering.rb python -m unittest discover -s tests - name: Build Jekyll site diff --git a/_includes/api_lua_v2.html b/_includes/api_lua_v2.html index 919c91259..137d9d3d3 100644 --- a/_includes/api_lua_v2.html +++ b/_includes/api_lua_v2.html @@ -32,7 +32,7 @@

Types

{% include ref_anchor_target.html element=alias %}

{{ alias.name }}

-

{{ alias.name | escape }} = {{ alias.target_type_html }}

+

{{ alias.name | escape }} = {{ alias.target_type_html }}

{{ alias.description }}

{%- if alias.examples.size > 0 -%} diff --git a/refdoc.py b/refdoc.py index e4f75e263..623191d6d 100644 --- a/refdoc.py +++ b/refdoc.py @@ -363,29 +363,22 @@ def prepare_lua_v2(api, current_page="", targets=None): } member_names = list(documented_members) if not member_names: - prefixes = (enum_name + "_", enum_name + ".") - member_names = sorted( - name for name in constants if name.startswith(prefixes)) + raise ValueError( + "enum %s must declare at least one explicit member" + % enum_name) resolved_members = [] for member_name in member_names: constant = constants.get(member_name) if constant: - previous_enum = constant.get("enum") - if previous_enum and previous_enum != enum_name: - raise ValueError( - "constant %s belongs to both %s and %s" - % (member_name, previous_enum, enum_name)) - constant["enum"] = enum_name - constant["is_enum_member"] = True - constant["value_type"] = enum_name + raise ValueError( + "enum %s member %s is also declared as a standalone " + "constant" % (enum_name, member_name)) documented = documented_members.get(member_name, {}) resolved_members.append({ "name": member_name, "doc": _link_lua_type_spans(( documented.get("doc") - or (constant or {}).get("description") - or (constant or {}).get("brief") or ""), current_page, targets), }) enum["members"] = resolved_members diff --git a/tests/test_api_lua_v2_rendering.rb b/tests/test_api_lua_v2_rendering.rb new file mode 100644 index 000000000..75d9f4a9d --- /dev/null +++ b/tests/test_api_lua_v2_rendering.rb @@ -0,0 +1,99 @@ +# frozen_string_literal: true + +require "fileutils" +require "json" +require "jekyll" +require "minitest/autorun" +require "tmpdir" + +class ApiLuaV2RenderingTest < Minitest::Test + ROOT = File.expand_path("..", __dir__) + INCLUDES = %w[ + api_lua_v2.html + api_lua_v2_parameters.html + api_lua_v2_signature.html + api_lua_v2_summary.html + ref_anchor_target.html + ref_anchorlink.html + ].freeze + + def test_member_markup_and_long_alias_signature + Dir.mktmpdir("defold-api-lua-v2-test") do |directory| + source = File.join(directory, "source") + destination = File.join(directory, "site") + includes = File.join(source, "_includes") + data = File.join(source, "_data") + FileUtils.mkdir_p([includes, data]) + + INCLUDES.each do |name| + FileUtils.cp( + File.join(ROOT, "_includes", name), + File.join(includes, name) + ) + end + + File.write( + File.join(source, "index.html"), + "---\n---\n{% include api_lua_v2.html ref=site.data.ref %}\n" + ) + File.write( + File.join(data, "ref.json"), + JSON.pretty_generate(reference_document) + ) + + site = Jekyll::Site.new(Jekyll.configuration( + "source" => source, + "destination" => destination, + "cache_dir" => File.join(directory, "cache"), + "quiet" => true + )) + site.process + + rendered = File.read(File.join(destination, "index.html")) + assert_includes( + rendered, + 'render.render_target_params = ' + ) + assert_includes rendered, "Use code formatting." + end + end + + private + + def reference_document + { + "info" => { + "brief" => "Render API", + "description_html" => "Render documentation." + }, + "elements" => [ + { + "type" => "TYPEDEF", + "name" => "render.render_target_params", + "brief" => "Render-target parameters.", + "target_type_html" => ( + "{ sample_count?:integer, " \ + "[graphics.BUFFER_TYPE]:render.render_target_buffer_params }" + ), + "description" => "Target configuration.", + "examples" => [] + }, + { + "type" => "STRUCT", + "name" => "render.render_target_buffer_params", + "brief" => "Render-target buffer parameters.", + "description" => "Buffer configuration.", + "examples" => [], + "members" => [ + { + "display_name" => "format", + "is_optional" => false, + "type_html" => "graphics.TEXTURE_FORMAT", + "doc" => "Use code formatting." + } + ] + } + ] + } + end +end diff --git a/tests/test_refdoc.py b/tests/test_refdoc.py index 40d8a4fbf..2e789f194 100644 --- a/tests/test_refdoc.py +++ b/tests/test_refdoc.py @@ -28,14 +28,10 @@ def test_prepares_v2_lua_types_and_enum_members(self): "type": "ENUM", "name": "go.EASING", "parameters": [], - "members": [], - }, - { - "type": "CONSTANT", - "name": "go.EASING_LINEAR", - "brief": "linear easing", - "description": "", - "parameters": [], + "members": [{ + "name": "go.EASING_LINEAR", + "doc": "Use linear easing.", + }], }, { "type": "CONSTANT", @@ -50,24 +46,81 @@ def test_prepares_v2_lua_types_and_enum_members(self): { "type": "STRUCT", "name": "on_input.action", - "members": [{"name": "pressed?", "type": "boolean"}], + "members": [{ + "name": "pressed?", + "type": "boolean", + "doc": "Use true when pressed.", + }], }, ], } prepared = refdoc.prepare_lua_v2(copy.deepcopy(api)) - enum, enum_constant, standalone, alias, record = prepared["elements"] + enum, standalone, alias, record = prepared["elements"] self.assertEqual("integer", enum["value_type"]) self.assertEqual( - [{"name": "go.EASING_LINEAR", "doc": "linear easing"}], + [{ + "name": "go.EASING_LINEAR", + "doc": "Use linear easing.", + }], enum["members"]) - self.assertTrue(enum_constant["is_enum_member"]) - self.assertEqual("go.EASING", enum_constant["value_type"]) self.assertFalse(standalone["is_enum_member"]) self.assertEqual("string | url", alias["target_type"]) self.assertEqual("pressed", record["members"][0]["display_name"]) self.assertTrue(record["members"][0]["is_optional"]) + self.assertEqual( + "Use true when pressed.", + record["members"][0]["doc"]) + + def test_v2_enum_requires_explicit_members(self): + api = { + "format_version": 2, + "info": {"api_language": "Lua"}, + "elements": [ + { + "type": "ENUM", + "name": "go.EASING", + "parameters": [], + "members": [], + }, + { + "type": "CONSTANT", + "name": "go.EASING_LINEAR", + "parameters": [], + }, + ], + } + + with self.assertRaisesRegex( + ValueError, + r"enum go\.EASING must declare at least one explicit member"): + refdoc.prepare_lua_v2(api) + + def test_v2_enum_rejects_duplicate_standalone_member(self): + api = { + "format_version": 2, + "info": {"api_language": "Lua"}, + "elements": [ + { + "type": "ENUM", + "name": "go.EASING", + "parameters": [], + "members": [{"name": "go.EASING_LINEAR", "doc": ""}], + }, + { + "type": "CONSTANT", + "name": "go.EASING_LINEAR", + "parameters": [], + }, + ], + } + + with self.assertRaisesRegex( + ValueError, + r"enum go\.EASING member go\.EASING_LINEAR is also declared " + r"as a standalone constant"): + refdoc.prepare_lua_v2(api) def test_links_documented_and_builtin_types(self): namespaces = { @@ -75,7 +128,14 @@ def test_links_documented_and_builtin_types(self): "format_version": 2, "info": {"api_language": "Lua"}, "elements": [ - {"type": "ENUM", "name": "go.PLAYBACK"}, + { + "type": "ENUM", + "name": "go.PLAYBACK", + "members": [{ + "name": "go.PLAYBACK_ONCE_FORWARD", + "doc": "Play once.", + }], + }, { "type": "FUNCTION", "name": "go.animate",