Update documentation

README.md

@@ -271,6 +271,26 @@ gui.Label{label="I am centered!", align_h = "centre"},
 This applies to other elements as well, because using HBox and Spacer to centre
 elements creates unnecessary containers.
 
+#### `gui.Stack`
+
+This container element places its children on top of each other. All child
+elements are expanded in both directions.
+
+Note that some elements (such as centred labels) won't pass clicks through to
+the element below them.
+
+Example:
+
+```lua
+gui.Stack{
+    min_w = 10,
+    gui.Button{label = "Hello world!"},
+    gui.Image{w = 1, h = 1, texture_name = "air.png", padding = 0.2, align_h = "left"},
+}
+```
+
+![Screenshot](https://user-images.githubusercontent.com/3182651/215946217-3705dbd1-4ec8-4aed-a9eb-381fecb2d8f2.png)
+
 ### Minetest formspec elements
 
 There is an auto-generated
@@ -344,18 +364,18 @@ gui.Button{
 },
 ```
 
+## Hiding elements
+
+Elements inside boxes can have `visible = false` set to hide them from the
+player. Elements hidden this way will still take up space like with
+`visibility: hidden;` in CSS.
+
 The style elements are invisible and won't affect padding.
 
 ## Experimental features
 
 These features might be broken in the future.
 
-### Hiding elements
-
-Elements inside boxes can have `visible = false` set to hide them from the
-player. Elements hidden this way will still take up space like with
-`visibility: hidden;` in CSS.
-
 ### `no_prepend[]`
 
 You can set `no_prepend = true` on the "root" element to disable formspec
@@ -379,23 +399,3 @@ end)
 ```
 
 ![Screenshot](https://user-images.githubusercontent.com/3182651/212222545-baee3669-15cd-410d-a638-c63b65a8811b.png)
-
-### `gui.Stack`
-
-This container element places its children on top of each other. All child
-elements are expanded in both directions.
-
-Note that some elements (such as centred labels and `gui.Box`) won't pass
-clicks through to the element below them.
-
-Example:
-
-```lua
-gui.Stack{
-    min_w = 10,
-    gui.Button{label = "Hello world!"},
-    gui.Image{w = 1, h = 1, texture_name = "air.png", padding = 0.2, align_h = "left"},
-}
-```
-
-![Screenshot](https://user-images.githubusercontent.com/3182651/215946217-3705dbd1-4ec8-4aed-a9eb-381fecb2d8f2.png)

elements.md

@@ -9,8 +9,8 @@ Equivalent to Minetest's `animated_image[]` element.
 **Example**
 ```lua
 gui.AnimatedImage {
-    w = 1, -- Optional
+    w = 1,
-    h = 2, -- Optional
+    h = 2,
     name = "my_animated_image", -- Optional
     texture_name = "Hello world!",
     frame_count = 3,
@@ -23,38 +23,6 @@ gui.AnimatedImage {
 }
 ```
 
-### `gui.Background`
-
-Equivalent to Minetest's `background[]` element.
-
-**Example**
-```lua
-gui.Background {
-    w = 1, -- Optional
-    h = 2, -- Optional
-    texture_name = "Hello world!",
-    auto_clip = false, -- Optional
-}
-```
-
-### `gui.Background9`
-
-Equivalent to Minetest's `background9[]` element.
-
-**Example**
-```lua
-gui.Background9 {
-    w = 1, -- Optional
-    h = 2, -- Optional
-    texture_name = "Hello world!",
-    auto_clip = false,
-    middle_x = 3,
-    middle_y = 4, -- Optional
-    middle_x2 = 5, -- Optional
-    middle_y2 = 6, -- Optional
-}
-```
-
 ### `gui.Box`
 
 Equivalent to Minetest's `box[]` element.
@@ -147,8 +115,8 @@ Equivalent to Minetest's `hypertext[]` element.
 **Example**
 ```lua
 gui.Hypertext {
-    w = 1, -- Optional
+    w = 1,
-    h = 2, -- Optional
+    h = 2,
     name = "my_hypertext", -- Optional
     text = "Hello world!",
 }
@@ -161,8 +129,8 @@ Equivalent to Minetest's `image[]` element.
 **Example**
 ```lua
 gui.Image {
-    w = 1, -- Optional
+    w = 1,
-    h = 2, -- Optional
+    h = 2,
     texture_name = "Hello world!",
     middle_x = 3, -- Optional
     middle_y = 4, -- Optional
@@ -178,8 +146,8 @@ Equivalent to Minetest's `image_button[]` element.
 **Example**
 ```lua
 gui.ImageButton {
-    w = 1, -- Optional
+    w = 1,
-    h = 2, -- Optional
+    h = 2,
     texture_name = "Hello world!",
     name = "my_image_button", -- Optional
     label = "Hello world!",
@@ -196,8 +164,8 @@ Equivalent to Minetest's `image_button_exit[]` element.
 **Example**
 ```lua
 gui.ImageButtonExit {
-    w = 1, -- Optional
+    w = 1,
-    h = 2, -- Optional
+    h = 2,
     texture_name = "Hello world!",
     name = "my_image_button_exit", -- Optional
     label = "Hello world!",
@@ -214,8 +182,8 @@ Equivalent to Minetest's `item_image[]` element.
 **Example**
 ```lua
 gui.ItemImage {
-    w = 1, -- Optional
+    w = 1,
-    h = 2, -- Optional
+    h = 2,
     item_name = "Hello world!",
 }
 ```
@@ -227,8 +195,8 @@ Equivalent to Minetest's `item_image_button[]` element.
 **Example**
 ```lua
 gui.ItemImageButton {
-    w = 1, -- Optional
+    w = 1,
-    h = 2, -- Optional
+    h = 2,
     item_name = "Hello world!",
     name = "my_item_image_button", -- Optional
     label = "Hello world!",
@@ -268,8 +236,8 @@ Equivalent to Minetest's `model[]` element.
 **Example**
 ```lua
 gui.Model {
-    w = 1, -- Optional
+    w = 1,
-    h = 2, -- Optional
+    h = 2,
     name = "my_model", -- Optional
     mesh = "Hello world!",
     textures = "Hello world!",
@@ -297,53 +265,6 @@ gui.Pwdfield {
 }
 ```
 
-### `gui.ScrollContainer`
-
-Equivalent to Minetest's `scroll_container[]` element.
-
-**Example**
-```lua
-gui.ScrollContainer {
-    w = 1, -- Optional
-    h = 2, -- Optional
-    scrollbar_name = "Hello world!",
-    orientation = "vertical",
-    scroll_factor = 3, -- Optional
-}
-```
-
-### `gui.Scrollbar`
-
-Equivalent to Minetest's `scrollbar[]` element.
-
-**Example**
-```lua
-gui.Scrollbar {
-    w = 1, -- Optional
-    h = 2, -- Optional
-    orientation = "vertical",
-    name = "my_scrollbar", -- Optional
-    value = 3,
-}
-```
-
-### `gui.Tabheader`
-
-Equivalent to Minetest's `tabheader[]` element.
-
-**Example**
-```lua
-gui.Tabheader {
-    h = 1, -- Optional
-    name = "my_tabheader", -- Optional
-    captions = "Hello world!",
-    current_tab = "Hello world!",
-    transparent = false, -- Optional
-    draw_border = false, -- Optional
-    w = 2, -- Optional
-}
-```
-
 ### `gui.Table`
 
 Equivalent to Minetest's `table[]` element.
@@ -397,12 +318,10 @@ Equivalent to Minetest's `tooltip[]` element.
 **Example**
 ```lua
 gui.Tooltip {
-    w = 1, -- Optional
-    h = 2, -- Optional
     tooltip_text = "Hello world!",
     bgcolor = "#FF0000", -- Optional
     fontcolor = "#FF0000", -- Optional
-    gui_element_name = "Hello world!", -- Optional
+    gui_element_name = "Hello world!",
 }
 ```
 

generate_docs.py

@@ -3,6 +3,11 @@ import collections, re, requests
 yaml = YAML(typ='safe')
 
 
+hide_elements = {
+    'background', 'background9', 'scroll_container', 'scrollbar', 'tabheader'
+}
+
+
 def fetch_elements():
     res = requests.get('https://github.com/luk3yx/minetest-formspec_ast/raw/'
                        'master/elements.yaml')
@@ -23,6 +28,12 @@ def search_for_fields(obj):
         yield from search_for_fields(e)
 
 
+def optional(element_name, field_name):
+    if field_name in ('w', 'h'):
+        return (element_name not in ('list', 'hypertext', 'model') and
+                '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())
@@ -36,14 +47,15 @@ def element_to_docs(element_name, variants):
     ]
 
     fields = collections.Counter(search_for_fields(variants))
-    if (('x', 'number') not in fields or
+    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
 
     for (field_name, field_type), count in fields.items():
-        if field_name in ('x', 'y'):
+        if (field_name in ('x', 'y') or (element_name == 'tooltip' and
+                                         field_name in ('w', 'h'))):
             continue
 
         if field_type == 'number':
@@ -66,8 +78,8 @@ def element_to_docs(element_name, variants):
             value = '<?>'
 
         line = f'    {field_name} = {value},'
-        if ((field_name in ('name', 'w', 'h') and element_name != 'list') or
+        if ((count < len(variants) or optional(element_name, field_name)) and
-                count < len(variants)):
+                field_name != 'gui_element_name'):
             line = line + ' -- Optional'
         res.append(line)