Skip to content

Commit f1792e5

Browse files
lgarber-akamailgarber-akamai
committed
Break template into macros
1 parent 8ddc6bc commit f1792e5

9 files changed

Lines changed: 225 additions & 162 deletions

‎linodecli/documentation/generator.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ class DocumentationGenerator:
2525
def __init__(self):
2626
self._template_env = Environment(
2727
loader=PackageLoader("linodecli.documentation", "templates"),
28+
extensions=["jinja2.ext.do"],
2829
autoescape=select_autoescape(),
2930
trim_blocks=True,
3031
lstrip_blocks=True,

‎linodecli/documentation/templates/_macros.rst.j2‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,22 @@
88

99
{{ description }}
1010

11-
{% endmacro %}
11+
{% endmacro %}
12+
13+
{% macro group_action_table(class, widths) %}
14+
15+
.. rst-class:: {{ class }}
16+
17+
.. list-table::
18+
:header-rows: 1
19+
:width: 100%
20+
:widths: {{ widths | join(" ") }}
21+
22+
{% for row in varargs %}
23+
{% for cell in row %}
24+
{{ "%s - %s" | format("*" if loop.index0 == 0 else " ", cell) | indent(first=True) }}
25+
{% endfor %}
26+
27+
{% endfor %}
28+
29+
{% endmacro %}

‎linodecli/documentation/templates/group_action.rst.j2‎

Lines changed: 16 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
{% macro render(action) %}
22
{% include "_roles.rst.j2" %}
33
{% import "group_action_params.rst.j2" as params_tmpl %}
4+
{% import "group_action_usage.rst.j2" as usage_tmpl %}
5+
{% import "group_action_samples.rst.j2" as samples_tmpl %}
6+
{% import "group_action_arguments.rst.j2" as args_tmpl %}
7+
{% import "group_action_filterable.rst.j2" as filterable_tmpl %}
8+
{% import "group_action_attributes.rst.j2" as attrs_tmpl %}
49

510
{% set action_title = action.action[0] %}
611
{% set action_title_format = "`%s <%s>`_" % (action_title, action.api_documentation_url) if action.api_documentation_url else action_title %}
@@ -20,156 +25,27 @@
2025

2126
{{ action.description }}
2227
{% if action.usage %}
23-
24-
.. rst-class:: action-subheading
25-
26-
Usage
27-
28-
.. rst-class:: action-subheading-description
29-
30-
The format accepted by this command.
31-
32-
.. code-block:: bash
33-
34-
{{ action.usage | indent(first=True) }}
35-
28+
{{ usage_tmpl.render(action.usage) }}
3629
{% endif %}
37-
{% if action.samples | length > 0 %}
38-
39-
.. rst-class:: action-subheading
40-
41-
Sample{% if action.samples | length > 1 %}s{% endif %}
42-
43-
44-
.. rst-class:: action-subheading-description
45-
46-
Examples of how this command might be used.
47-
48-
{% for sample in action.samples %}
4930

50-
.. code-block:: bash
51-
52-
{{ sample | indent(first=True) }}
53-
54-
{% endfor %}
31+
{% if action.samples | length > 0 %}
32+
{{ samples_tmpl.render(action.samples) }}
5533
{% endif %}
56-
{{ params_tmpl.render(action) }}
57-
{% if action.argument_sections | length > 0 %}
58-
59-
.. rst-class:: action-subheading
60-
61-
Arguments
62-
63-
.. rst-class:: action-subheading-description
64-
65-
Additional fields used to execute this request.
66-
67-
{% for section in action.argument_sections %}
68-
{% if section.name | length > 0 %}
69-
.. _commands_{{ action.command }}_{{ action.action[0] }}_argument_sections_{{ section.name }}:
70-
71-
.. rst-class:: action-section-header
72-
73-
{{ section.name }}
7434

35+
{% if action.parameters | length > 0 %}
36+
{{ params_tmpl.render(action.parameters) }}
7537
{% endif %}
76-
.. rst-class:: action-argument-section-table
77-
78-
.. list-table::
79-
:header-rows: 1
80-
:width: 100%
81-
:widths: 1 1 1 97
82-
83-
* - Name
84-
- Required
85-
- Type
86-
- Description
87-
88-
{% for argument in section.entries %}
89-
* - :action-table-field-name:`\-\-{{ argument.path }}`
90-
{% if argument.is_parent and argument.path in action.argument_sections_names %}
91-
:ref:`(section) <commands_{{ action.command }}_{{ action.action[0] }}_argument_sections_{{ argument.path }}>`
92-
{% endif %}
93-
- {% if argument.required %}:action-table-field-required:`Yes`{% else %}:action-table-field-optional:`No`{% endif %}
9438

95-
- :action-table-field-type:`{{ argument.type }}`
96-
- {% if argument.description %}{{ argument.description }}{% else %}N/A{% endif %}
97-
98-
{% endfor %}
99-
{% endfor %}
39+
{% if action.argument_sections | length > 0 %}
40+
{{ args_tmpl.render(action.command, action.action[0], action.argument_sections, action.argument_sections_names) }}
10041
{% endif %}
101-
{% if action.filterable_attributes | length > 0 %}
102-
103-
.. rst-class:: action-subheading
104-
105-
Filterable Attributes
106-
107-
.. rst-class:: action-subheading-description
108-
109-
Arguments used to define a filter for response entries.
11042

111-
.. rst-class:: action-filterable-field-table
112-
113-
.. list-table::
114-
:header-rows: 1
115-
:width: 100%
116-
:widths: 1 1 98
117-
118-
* - Name
119-
- Type
120-
- Description
121-
122-
{% for attr in action.filterable_attributes %}
123-
* - :action-table-field-name:`\-\-{{ attr.name }}`
124-
- :action-table-field-type:`{{ attr.type }}`
125-
- {% if attr.description %}{{ attr.description }}{% else %}N/A{% endif %}
126-
127-
{% endfor %}
43+
{% if action.filterable_attributes | length > 0 %}
44+
{{ filterable_tmpl.render(action.filterable_attributes) }}
12845
{% endif %}
129-
{% if action.attribute_sections | length > 0%}
130-
131-
.. rst-class:: action-subheading
132-
133-
Result Attributes
134-
135-
.. rst-class:: action-subheading-description
136-
137-
The attributes returned by this command.
138-
139-
.. rst-class:: action-attribute-table
140-
141-
{% for section in action.attribute_sections %}
142-
{% if section.name | length > 0 %}
143-
.. _commands_{{ action.command }}_{{ action.action[0] }}_attribute_sections_{{ section.name }}:
144-
145-
.. rst-class:: action-section-header
146-
147-
{{ section.name }}
14846

47+
{% if action.attribute_sections | length > 0%}
48+
{{ attrs_tmpl.render(action.command, action.action[0], action.attribute_sections, action.attribute_sections_names) }}
14949
{% endif %}
150-
.. rst-class:: action-attribute-section-table
151-
152-
.. list-table::
153-
:header-rows: 1
154-
:width: 100%
155-
:widths: 1 1 1 97
156-
157-
* - Name
158-
- Type
159-
- Example
160-
- Description
16150

162-
{% for attribute in section.entries %}
163-
* - :action-table-field-name:`{{ attribute.name }}`
164-
{% if attribute.name in action.attribute_sections_names %}
165-
:ref:`(section) <commands_{{ action.command }}_{{ action.action[0] }}_attribute_sections_{{ attribute.path }}>`
166-
{% endif %}
167-
- :action-table-field-type:`{{ attribute.type }}`
168-
- {% if attribute.example %}:json:`{{ attribute.example | tojson }}`{% else %}?{% endif %}
169-
170-
- {% if attribute.description %}{{ attribute.description }}{% else %}N/A{% endif %}
171-
172-
{% endfor %}
173-
{% endfor %}
174-
{% endif %}
17551
{% endmacro %}

‎linodecli/documentation/templates/group_action_arguments.rst.j2‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{% macro render(command, action, sections, section_names) %}
2+
{% include "_roles.rst.j2" %}
3+
{% import "_macros.rst.j2" as macros %}
4+
5+
{{
6+
macros.group_action_subheading(
7+
"Arguments",
8+
"Additional fields used to execute this request."
9+
)
10+
}}
11+
12+
{% for section in sections %}
13+
{% if section.name | length > 0 %}
14+
15+
.. _commands_{{ command }}_{{ action }}_argument_sections_{{ section.name }}:
16+
17+
.. rst-class:: action-section-header
18+
19+
{{ section.name }}
20+
21+
{% endif %}
22+
23+
{% set rows = [] %}
24+
{% for arg in section.entries %}
25+
{%
26+
do rows.append(
27+
[
28+
":action-table-field-name:`\-\-%s` %s" % (
29+
arg.path,
30+
":ref:`(section) <commands_%s_%s_argument_sections_%s>`" % (command, action, arg.path)
31+
if arg.is_parent and arg.path in section_names else ""
32+
),
33+
":action-table-field-required:`Yes`" if arg.required else ":action-table-field-optional:`No`",
34+
":action-table-field-type:`%s`" % arg.type,
35+
arg.description if arg.description else "N/A"
36+
]
37+
)
38+
%}
39+
{% endfor %}
40+
{{
41+
macros.group_action_table(
42+
"action-argument-section-table",
43+
[1, 1, 1, 97],
44+
["Name", "Required", "Type", "Description"],
45+
*rows
46+
)
47+
}}
48+
{% endfor %}
49+
50+
{% endmacro %}

‎linodecli/documentation/templates/group_action_attributes.rst.j2‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{% macro render(command, action, sections, section_names) %}
2+
{% include "_roles.rst.j2" %}
3+
{% import "_macros.rst.j2" as macros %}
4+
5+
{{
6+
macros.group_action_subheading(
7+
"Result Attributes",
8+
"The attributes returned by this command."
9+
)
10+
}}
11+
12+
{% for section in sections %}
13+
{% if section.name | length > 0 %}
14+
15+
.. _commands_{{ command }}_{{ action }}_attribute_sections_{{ section.name }}:
16+
17+
.. rst-class:: action-section-header
18+
19+
{{ section.name }}
20+
21+
{% endif %}
22+
{% set rows = [] %}
23+
{% for attr in section.entries %}
24+
{%
25+
do rows.append(
26+
[
27+
":action-table-field-name:`%s` %s" % (
28+
attr.name,
29+
":ref:`(section) <commands_%s_%s_attribute_sections_%s>`" % (command, action, attr.name)
30+
if attr.is_parent and attr.path in section_names else ""
31+
),
32+
":action-table-field-type:`%s`" % attr.type,
33+
":json:`%s`" % (attr.type | tojson) if attr.example else "",
34+
attr.description if attr.description else "N/A"
35+
]
36+
)
37+
%}
38+
{% endfor %}
39+
{{
40+
macros.group_action_table(
41+
"action-attribute-section-table",
42+
[1, 1, 1, 97],
43+
["Name", "Type", "Example", "Description"],
44+
*rows
45+
)
46+
}}
47+
{% endfor %}
48+
49+
{% endmacro %}

‎linodecli/documentation/templates/group_action_filterable.rst.j2‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{% macro render(attributes) %}
2+
{% include "_roles.rst.j2" %}
3+
{% import "_macros.rst.j2" as macros %}
4+
5+
{{
6+
macros.group_action_subheading(
7+
"Filterable Attributes",
8+
"Arguments used to define a filter for response entries."
9+
)
10+
}}
11+
12+
{% set rows = [] %}
13+
{% for attr in attributes %}
14+
{%
15+
do rows.append(
16+
[
17+
":action-table-field-name:`\-\-%s`" % attr.name,
18+
":action-table-field-type:`%s`" % attr.type,
19+
attr.description if attr.description else "N/A"
20+
]
21+
)
22+
%}
23+
{% endfor %}
24+
{{
25+
macros.group_action_table(
26+
"action-filterable-field-table",
27+
[1, 1, 98],
28+
["Name", "Type", "Description"],
29+
*rows
30+
)
31+
}}
32+
33+
{% endmacro %}

0 commit comments

Comments
 (0)