Patch v2 docs

.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

_includes/api_lua_v2.html

@@ -32,7 +32,7 @@ <h2 id="types" data-pagefind-weight="7">Types</h2>
 	{% include ref_anchor_target.html element=alias %}
 	<div data-pagefind-weight="8">
 		<h4 id="{% include ref_anchorlink.html element=alias %}">{{ alias.name }}<a href="#{% include ref_anchorlink.html element=alias %}" class="anchor-link"></a></h4>
-		<p><code>{{ alias.name | escape }} = {{ alias.target_type_html }}</code></p>
+		<p><code class="api-lua-v2-signature">{{ alias.name | escape }} = {{ alias.target_type_html }}</code></p>
 		<p>{{ alias.description }}</p>
 
 		{%- if alias.examples.size > 0 -%}

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

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,
+        '<code class="api-lua-v2-signature">render.render_target_params = '
+      )
+      assert_includes rendered, "Use <code>code</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>code</code> formatting."
+            }
+          ]
+        }
+      ]
+    }
+  end
+end

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 <code>linear</code> easing.",
+                    }],
                 },
                 {
                     "type": "CONSTANT",
@@ -50,32 +46,96 @@ 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 <code>true</code> 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 <code>linear</code> 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 <code>true</code> 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 = {
             "go-lua": {
                 "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",