Improve elements.md

elements.md

@@ -12,7 +12,7 @@ gui.AnimatedImage {
     w = 1,
     h = 2,
     name = "my_animated_image", -- Optional
-    texture_name = "Hello world!",
+    texture_name = "texture.png",
     frame_count = 3,
     frame_duration = 4,
     frame_start = 5, -- Optional
@@ -87,7 +87,7 @@ gui.Dropdown {
     w = 1, -- Optional
     h = 2, -- Optional
     name = "my_dropdown", -- Optional
-    items = "Hello world!",
+    items = {"Hello world!", ...},
     selected_idx = 3,
     index_event = false, -- Optional
 }
@@ -131,7 +131,7 @@ Equivalent to Minetest's `image[]` element.
 gui.Image {
     w = 1,
     h = 2,
-    texture_name = "Hello world!",
+    texture_name = "texture.png",
     middle_x = 3, -- Optional
     middle_y = 4, -- Optional
     middle_x2 = 5, -- Optional
@@ -148,12 +148,12 @@ Equivalent to Minetest's `image_button[]` element.
 gui.ImageButton {
     w = 1,
     h = 2,
-    texture_name = "Hello world!",
+    texture_name = "texture.png",
     name = "my_image_button", -- Optional
     label = "Hello world!",
     noclip = false, -- Optional
     drawborder = false, -- Optional
-    pressed_texture_name = "Hello world!", -- Optional
+    pressed_texture_name = "texture.png", -- Optional
 }
 ```
 
@@ -166,12 +166,12 @@ Equivalent to Minetest's `image_button_exit[]` element.
 gui.ImageButtonExit {
     w = 1,
     h = 2,
-    texture_name = "Hello world!",
+    texture_name = "texture.png",
     name = "my_image_button_exit", -- Optional
     label = "Hello world!",
     noclip = false, -- Optional
     drawborder = false, -- Optional
-    pressed_texture_name = "Hello world!", -- Optional
+    pressed_texture_name = "texture.png", -- Optional
 }
 ```
 
@@ -240,7 +240,7 @@ gui.Model {
     h = 2,
     name = "my_model", -- Optional
     mesh = "Hello world!",
-    textures = "Hello world!",
+    textures = {"texture.png", ...},
     rotation_x = 3, -- Optional
     rotation_y = 4, -- Optional
     continuous = false, -- Optional
@@ -275,11 +275,39 @@ gui.Table {
     w = 1, -- Optional
     h = 2, -- Optional
     name = "my_table", -- Optional
-    cells = "Hello world!",
+    cells = {"Hello world!", ...},
     selected_idx = 3,
 }
 ```
 
+### `gui.TableColumns`
+
+Equivalent to Minetest's `tablecolumns[]` element.
+
+**Example**
+```lua
+gui.TableColumns {
+    tablecolumns = {
+        {
+            type = "text",
+            opts = {field = "value"},
+        },
+        ...
+    }
+}
+```
+
+### `gui.TableOptions`
+
+Equivalent to Minetest's `tableoptions[]` element.
+
+**Example**
+```lua
+gui.TableOptions {
+    opts = {field = "value"},
+}
+```
+
 ### `gui.Textarea`
 
 Equivalent to Minetest's `textarea[]` element.
@@ -305,7 +333,7 @@ gui.Textlist {
     w = 1, -- Optional
     h = 2, -- Optional
     name = "my_textlist", -- Optional
-    listelems = "Hello world!",
+    listelems = {"Hello world!", ...},
     selected_idx = 3, -- Optional
     transparent = false, -- Optional
 }
@@ -321,7 +349,7 @@ gui.Tooltip {
     tooltip_text = "Hello world!",
     bgcolor = "#FF0000", -- Optional
     fontcolor = "#FF0000", -- Optional
-    gui_element_name = "Hello world!",
+    gui_element_name = "my_button",
 }
 ```
 

generate_docs.py

@@ -6,6 +6,8 @@ yaml = YAML(typ='safe')
 hide_elements = {
     'background', 'background9', 'scroll_container', 'scrollbar', 'tabheader'
 }
+special_case_names = {'tablecolumns': 'TableColumns',
+                      'tableoptions': 'TableOptions'}
 
 
 def fetch_elements():
@@ -14,14 +16,17 @@ def fetch_elements():
     return yaml.load(res.text)
 
 
-def search_for_fields(obj):
+Field = collections.namedtuple('Field', 'name type is_list', defaults=(False,))
+
+
+def search_for_fields(obj, *, is_list=False):
     assert isinstance(obj, (list, tuple))
     if len(obj) == 2:
         if obj[1] == '...':
-            yield from search_for_fields(obj[0])
+            yield from search_for_fields(obj[0], is_list=True)
             return
         if isinstance(obj[0], str) and isinstance(obj[1], str):
-            yield tuple(obj)
+            yield Field(obj[0], obj[1], is_list)
             return
 
     for e in obj:
@@ -34,11 +39,21 @@ def optional(element_name, field_name):
                 'image' not in element_name)
     return field_name == 'name'
 
-def element_to_docs(element_name, variants):
-    flow_name = re.sub(r'_(.)', lambda m: m.group(1).upper(),
-                       element_name.capitalize())
 
-    res = [
+def element_to_docs(element_name, variants):
+    if element_name in special_case_names:
+        flow_name = special_case_names[element_name]
+    else:
+        flow_name = re.sub(r'_(.)', lambda m: m.group(1).upper(),
+                           element_name.capitalize())
+
+    fields = collections.Counter(search_for_fields(variants))
+    if ((element_name in hide_elements or Field('x', 'number') not in fields or
+            all(field.name in ('x', 'y') for field in fields)) and
+            element_name not in special_case_names):
+        return ''
+
+    lines = [
         f'### `gui.{flow_name}`\n',
         f"Equivalent to Minetest's `{element_name}[]` element.\n",
         '**Example**',
@@ -46,47 +61,61 @@ def element_to_docs(element_name, variants):
         f'gui.{flow_name} {{'
     ]
 
-    fields = collections.Counter(search_for_fields(variants))
-    if (element_name in hide_elements or ('x', 'number') not in fields or
-            all(field_name in ('x', 'y') for field_name, _ in fields)):
-        return ''
-
     num = 1
+    indent = ' ' * 4
+    if element_name == 'tablecolumns':
+        lines.append(f'{indent}tablecolumns = {{')
+        lines.append(f'{indent}{indent}{{')
+        indent += ' ' * 8
 
-    for (field_name, field_type), count in fields.items():
+    for field, count in fields.items():
-        if (field_name in ('x', 'y') or (element_name == 'tooltip' and
+        if (field.name in ('x', 'y') or (element_name == 'tooltip' and
-                                         field_name in ('w', 'h'))):
+                                         field.name in ('w', 'h'))):
             continue
 
-        if field_type == 'number':
+        if field.type == 'number':
             value = num
             num += 1
-        elif field_type == 'string':
+        elif field.type == 'string':
-            if field_name == 'name':
+            if field.name == 'name':
                 value = f'"my_{element_name}"'
-            elif field_name == 'orientation':
+            elif field.name == 'orientation':
                 value = '"vertical"'
-            elif 'color' in field_name:
+            elif 'color' in field.name:
                 value = '"#FF0000"'
+            elif field.name == 'type':
+                value = '"text"'
+            elif field.name == 'gui_element_name':
+                value = '"my_button"'
+            elif 'texture' in field.name:
+                value = '"texture.png"'
             else:
                 value = '"Hello world!"'
-        elif field_type in ('boolean', 'fullscreen'):
+        elif field.type in ('boolean', 'fullscreen'):
             value = 'false'
-        elif field_type == 'table':
+        elif field.type == 'table':
             value = '{field = "value"}'
         else:
             value = '<?>'
 
-        line = f'    {field_name} = {value},'
+        if field.is_list and field.type != 'table':
-        if ((count < len(variants) or optional(element_name, field_name)) and
+            value = f'{{{value}, ...}}'
-                field_name != 'gui_element_name'):
+
+        line = f'{indent}{field.name} = {value},'
+        if ((count < len(variants) or optional(element_name, field.name)) and
+                field.name != 'gui_element_name'):
             line = line + ' -- Optional'
-        res.append(line)
+        lines.append(line)
 
-    res.append('}')
+    if element_name == 'tablecolumns':
-    res.append('```')
+        lines.append(' ' * 8 + '},')
+        lines.append(' ' * 8 + '...')
+        lines.append(' ' * 4 + '}')
 
-    return '\n'.join(res)
+    lines.append('}')
+    lines.append('```')
+
+    return '\n'.join(lines)
 
 
 if __name__ == '__main__':