Various formatting improvements

Author: lgarber-akamai

docs/static/overlay.css

@@ -22,7 +22,11 @@ td {
     width: 150px !important;
 }
 
-/* Custom formatting for actions */
+
+/*
+Custom formatting for actions
+*/
+
 .action-subheading {
     margin-bottom: 4px !important;
 }
@@ -32,6 +36,39 @@ td {
     margin-bottom: 12px !important;
 }
 
+.action-argument-section-header {
+    color: #606060 !important;
+    font-weight: 700 !important;
+    padding-top: 10px !important;
+    margin-bottom: 12px !important;
+    font-size: 95% !important;
+}
+
 .action-argument-required {
-    color: red !important;
+    color: #CD5C5C !important;
+    font-weight: bolder !important;
 }
+
+/*
+Formatting for generated tables
+*/
+
+/* Prevent word wrapping on `Name` fields */
+.action-argument-section-table > tbody tr > td:nth-child(1) *,
+.action-parameter-table > tbody tr > td:nth-child(1) *,
+.action-filterable-field-table > tbody tr > td:nth-child(1) * {
+    word-wrap: unset !important;
+    white-space: nowrap !important;
+}
+
+/* Center-align `Required` and `Type` columns */
+.action-argument-section-table > tbody tr > td:nth-child(2),
+.action-argument-section-table > thead tr > th:nth-child(2),
+.action-argument-section-table > tbody tr > td:nth-child(3),
+.action-argument-section-table > thead tr > th:nth-child(3),
+.action-parameter-table > tbody tr > td:nth-child(2),
+.action-parameter-table > thead tr > th:nth-child(2),
+.action-filterable-field-table > tbody tr > td:nth-child(2),
+.action-filterable-field-table > thead tr > th:nth-child(2) {
+    text-align: center !important;
+}

linodecli/documentation/template_data.py

@@ -2,9 +2,10 @@
 Contains all structures used to render documentation templates.
 """
 
+from collections import defaultdict
 from dataclasses import dataclass, field
 from io import StringIO
-from typing import Dict, List, Optional, Self
+from typing import Dict, List, Optional, Self, Set
 
 from linodecli.baked import OpenAPIOperation
 from linodecli.baked.operation import OpenAPIOperationParameter
@@ -145,6 +146,16 @@ def from_openapi(cls, param: OpenAPIOperationParameter) -> Self:
         )
 
 
+@dataclass
+class ArgumentSection:
+    """
+    Represents a single section of arguments.
+    """
+
+    name: str
+    arguments: List[Argument]
+
+
 @dataclass
 class Action:
     """
@@ -164,7 +175,8 @@ class Action:
     filterable_attrs: List[FilterableAttribute] = field(
         default_factory=lambda: []
     )
-    arguments: List[Argument] = field(default_factory=lambda: [])
+    argument_sections: List[ArgumentSection] = field(default_factory=lambda: [])
+    argument_sections_names: Set[str] = field(default_factory=lambda: {})
 
     @classmethod
     def from_openapi(cls, operation: OpenAPIOperation) -> Self:
@@ -206,15 +218,29 @@ def from_openapi(cls, operation: OpenAPIOperation) -> Self:
             ]
 
         if operation.args:
-            result.arguments = sorted(
+            sections = defaultdict(lambda: [])
+
+            for arg in operation.args:
+                if not isinstance(arg, OpenAPIRequestArg):
+                    continue
+
+                sections[arg.prefix or ""].append(Argument.from_openapi(arg))
+
+            result.argument_sections = sorted(
                 [
-                    Argument.from_openapi(arg)
-                    for arg in operation.args
-                    if isinstance(arg, OpenAPIRequestArg)
+                    ArgumentSection(
+                        name=k,
+                        arguments=sorted(
+                            v, key=lambda arg: (not arg.required, arg.path)
+                        ),
+                    )
+                    for k, v in sections.items()
                 ],
-                key=lambda arg: (not arg.required, arg.path),
+                key=lambda section: section.name,
             )
 
+            result.argument_sections_names = set(sections.keys())
+
         if operation.method == "get" and operation.response_model.is_paginated:
             result.filterable_attrs = sorted(
                 [

linodecli/documentation/templates/group.rst.j2

@@ -1,11 +1,9 @@
-.. role:: action-subheading
-.. role:: action-subheading-description
 .. role:: action-argument-required
 
 {% macro action_details(action) %}
 {% set action_title = action.action[0] %}
 {% set action_title_format = "`%s <%s>`_" % (action_title, action.api_documentation_url) if action.api_documentation_url else action_title %}
-.. _{{ action.command }}_{{ action.action[0] }}:
+.. _commands_{{ action.command }}_{{ action.action[0] }}:
 
 {{ action_title_format }}
 {{ "-" * (action_title_format | length) }}
@@ -26,7 +24,10 @@
 
     .. rubric:: Usage
 
-:action-subheading-description:`The format accepted by this command.`
+
+.. cssclass:: action-subheading-description
+
+    The format accepted by this command.
 
 ..  code-block:: bash
 
@@ -40,7 +41,9 @@
     .. rubric:: Sample{% if action.samples | length > 1 %}s{% endif %}
 
 
-:action-subheading-description:`Examples of how this command might be used.`
+.. cssclass:: action-subheading-description
+
+    Examples of how this command might be used.
 
 {% for sample in action.samples %}
 
@@ -56,7 +59,12 @@
 
     .. rubric:: Parameters
 
-:action-subheading-description:`Positional parameters used to define the resource this command should target.`
+.. cssclass:: action-subheading-description
+
+    Positional parameters used to define the resource this command should target.
+
+
+.. rst-class:: action-parameter-table
 
 ..  list-table::
     :header-rows: 1
@@ -74,38 +82,63 @@
 
 {% endfor %}
 {% endif %}
-{% if action.arguments | length > 0 %}
+{% if action.argument_sections | length > 0 %}
 
 .. cssclass:: action-subheading
 
     .. rubric:: Arguments
 
-:action-subheading-description:`Additional fields used to execute this request.`
+.. cssclass:: action-subheading-description
+
+    Additional fields used to execute this request.
+
+{% for section in action.argument_sections %}
+{% if section.name | length > 0 %}
+.. _commands_{{ action.command }}_{{ action.action[0] }}_argument_sections_{{ section.name }}:
+
+.. cssclass:: action-argument-section-header
+
+    {{ section.name }}
+{% endif %}
+
+.. rst-class:: action-argument-section-table
 
 ..  list-table::
     :header-rows: 1
     :width: 100%
-    :widths: 15 10 10 65
+    :widths: 1 10 10 79
 
     * - Name
       - Required
       - Type
       - Description
 
-{% for argument in action.arguments %}
+{% for argument in section.arguments %}
     * - :code:`--{{ argument.path }}`
+    {% if argument.is_parent and argument.path in action.argument_sections_names %}
+        :ref:`(section) <commands_{{ action.command }}_{{ action.action[0] }}_argument_sections_{{ argument.path }}>`
+    {% endif %}
       - {% if argument.required %}:action-argument-required:`Yes`{% else %}No{% endif %}
 
       - {{ argument.type }}
       - {% if argument.description %}{{ argument.description }}{% else %}N/A{% endif %}
 
+{% endfor %}
 {% endfor %}
 {% endif %}
 {% if action.filterable_attrs | length > 0 %}
 
-.. rubric:: Filterable Attributes
+.. cssclass:: action-subheading
+
+    .. rubric:: Filterable Attributes
 
-`Arguments used to define a filter for response entries.`
+
+.. cssclass:: action-subheading-description
+
+    Arguments used to define a filter for response entries.
+
+
+.. rst-class:: action-filterable-field-table
 
 ..  list-table::
     :header-rows: 1
@@ -136,4 +169,4 @@ This section details {{ pretty_name[:-1] if pretty_name[-1] == "s" else pretty_n
 ------------
 {% endif %}
 
-{% endfor %}
+{% endfor %}

linodecli/helpers.py

@@ -6,7 +6,7 @@
 import os
 from argparse import ArgumentParser
 from pathlib import Path
-from typing import Callable, List, Optional, TypeVar
+from typing import Any, Callable, List, Optional, TypeVar
 from urllib.parse import urlparse
 
 API_HOST_OVERRIDE = os.getenv("LINODE_CLI_API_HOST")
@@ -137,19 +137,20 @@ def sorted_actions_smart(
     :returns: The ordered actions.
     """
 
-    result = []
-    root_actions, other_actions = [], []
+    def __key(action: T) -> Any:
+        name = key(action)
 
-    for action in sorted(actions, key=key):
-        action_key = key(action)
+        # Prioritize CRUD operations
+        for i, crud_operation in enumerate(
+            ["list", "view", "create", "update", "delete"]
+        ):
+            name = name.replace(crud_operation, str(i))
 
-        if "-" not in action_key:
-            root_actions.append(action)
-            continue
+        return (
+            # Prioritize root operations
+            "-" in name,
+            # Sort everything else
+            name,
+        )
 
-        other_actions.append(action)
-
-    result.extend(root_actions)
-    result.extend(other_actions)
-
-    return result
+    return sorted(actions, key=__key)