Skip to content

Commit c4da9d4

Browse files
lgarber-akamailgarber-akamai
committed
Various CI changes
1 parent a664501 commit c4da9d4

24 files changed

+569
-80840
lines changed

‎.github/workflows/publish-docs.yml renamed to ‎.github/workflows/documentation.yml

Lines changed: 33 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ on:
1313

1414
jobs:
1515
build:
16-
name: Build the documentation
16+
name: Build
1717
runs-on: ubuntu-latest
1818
steps:
1919
- name: Checkout repository
@@ -73,19 +73,18 @@ jobs:
7373
name: generated-docs-html
7474
path: docs/build/html
7575

76-
publish:
77-
name: Publish the documentation
76+
pages-commit:
77+
name: Commit to Pages Branch
7878
runs-on: ubuntu-latest
7979
needs:
8080
- build
8181
# Make sure we avoid a race condition =)
8282
concurrency:
83-
group: "pages"
83+
group: "docs-stage"
8484
cancel-in-progress: false
8585
permissions:
8686
contents: write
87-
pages: write
88-
id-token: write
87+
8988
if: (github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'dev' || github.ref_name == 'new/doc-generation' )) || (github.ref_type == 'tag')
9089
steps:
9190
- name: Checkout the documentation branch
@@ -101,37 +100,52 @@ jobs:
101100
if: "${{ steps.checkout-docs.outcome != 'success' }}"
102101
run: git switch --orphan static/docs
103102

104-
- name: Ensure any previous documentation for this branch are removed
103+
- name: Ensure any previous documentation for this branch is removed
105104
run: rm -rf "./${{ github.ref_name }}"
106105

107-
- name: Download the artifact from the previous job
106+
- name: Download the artifact from the build job
108107
uses: actions/download-artifact@v4
109108
with:
110109
name: generated-docs-html
111110
path: "${{ github.ref_name }}"
112111

113112
- name: Override the latest version if necessary
114-
if: ${{ github.event_name == 'release' }}
113+
if: ${{ github.ref_type == 'tag' }}
115114
run: |
116115
rm -rf latest && cp -r ${{ github.ref_name }} latest
117116
117+
- name: Overlay static files
118+
run: |
119+
echo "<head><meta http-equiv='refresh' content='0; URL=latest/index.html'></head>" > index.html;
120+
touch .nojekyll
121+
118122
- name: Commit and push this change
119123
run: |
120124
git config user.name "Documentation Publisher";
121125
git config user.email "[email protected]";
122126
git add .;
123-
git commit --allow-empty -m "Rebuild ${{ github.ref_name }} from ${{ github.sha }}";
127+
git commit --allow-empty -m "Build ${{ github.ref_name }} from ${{ github.sha }}";
124128
git push origin static/docs;
125129
126-
- name: Configure GitHub Pages
127-
uses: actions/configure-pages@v5
130+
upload-release-asset:
131+
name: Upload Release Asset
132+
runs-on: ubuntu-latest
133+
needs:
134+
- build
135+
if: github.ref_type == 'tag'
136+
steps:
137+
- name: Download the artifact from the previous job
138+
uses: actions/download-artifact@v4
128139
with:
129-
enablement: true
140+
name: generated-docs-html
141+
path: ".build/${{ github.ref_name }}"
130142

131-
- name: Push the rendered documentation site to GitHub Pages
132-
uses: actions/upload-pages-artifact@v3
133-
with:
134-
path: .
143+
- name: Archive the built documentation
144+
run: |
145+
cd .build/${{ github.ref_name }} && tar -czvf ../documentation.tar.gz *
135146
136-
- name: Deploy to GitHub Pages
137-
uses: actions/deploy-pages@v4
147+
- name: Upload the documentation as a release asset
148+
uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191
149+
with:
150+
files: .build/documentation.tar.gz
151+
tag_name: ${{ github.ref_name }}

‎Makefile

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,6 @@ ifdef TEST_CASE
99
TEST_CASE_COMMAND = -k $(TEST_CASE)
1010
endif
1111

12-
# TODO: Revert this once the corrected spec is available.
13-
SPEC := ./openapi.yaml.tmp
14-
1512
SPEC_VERSION ?= latest
1613
ifndef SPEC
1714
override SPEC = $(shell ./resolve_spec_url ${SPEC_VERSION})

‎docs/index.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
linode-cli Documentation
2-
========================
3-
4-
.. image:: static/demo.gif
5-
:alt: Linode CLI Demo
1+
linode-cli
2+
==========
63

74
Welcome to the `linode-cli` documentation!
85

96
For installation instructions and usage guides, please
107
refer to the sidebar of this page or the Table of Contents below.
118

9+
.. image:: static/demo.gif
10+
:alt: Linode CLI Demo
11+
1212
Table of Contents
1313
-----------------
1414

‎docs/static/overlay.css

Lines changed: 53 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,66 @@ td {
2222
width: 150px !important;
2323
}
2424

25-
/* Custom formatting for actions */
25+
/*
26+
Custom formatting for actions
27+
*/
2628
.action-subheading {
2729
margin-bottom: 4px !important;
30+
font-weight: 700 !important;
2831
}
2932

3033
.action-subheading-description {
3134
font-size: 90% !important;
3235
margin-bottom: 12px !important;
3336
}
3437

35-
.action-argument-required {
36-
color: red !important;
38+
.action-section-header {
39+
color: #606060 !important;
40+
font-weight: 700 !important;
41+
padding-top: 10px !important;
42+
margin-bottom: 12px !important;
43+
font-size: 95% !important;
44+
}
45+
46+
.action-table-field-name,
47+
.action-table-field-optional,
48+
.action-table-field-required,
49+
.action-table-field-type {
50+
font-size: 85% !important;
51+
font-family: SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace !important;
52+
}
53+
54+
.action-table-field-required {
55+
color: #E74C3C !important;
56+
}
57+
58+
/*
59+
Formatting for generated tables
60+
*/
61+
62+
/* Prevent word wrapping on `Name` and `Example` fields */
63+
.action-argument-section-table > tbody tr > td:nth-child(1) *,
64+
.action-parameter-table > tbody tr > td:nth-child(1) *,
65+
.action-filterable-field-table > tbody tr > td:nth-child(1) *,
66+
.action-attribute-section-table > tbody tr > td:nth-child(1) *,
67+
.action-attribute-section-table > tbody tr > td:nth-child(3) * {
68+
word-wrap: unset !important;
69+
white-space: nowrap !important;
3770
}
71+
72+
/* Center-align `Required`, and `Type` columns */
73+
.action-argument-section-table > tbody tr > td:nth-child(2),
74+
.action-argument-section-table > thead tr > th:nth-child(2),
75+
.action-argument-section-table > tbody tr > td:nth-child(3),
76+
.action-argument-section-table > thead tr > th:nth-child(3),
77+
78+
.action-attribute-section-table > tbody tr > td:nth-child(2),
79+
.action-attribute-section-table > thead tr > th:nth-child(2),
80+
81+
.action-parameter-table > tbody tr > td:nth-child(2),
82+
.action-parameter-table > thead tr > th:nth-child(2),
83+
84+
.action-filterable-field-table > tbody tr > td:nth-child(2),
85+
.action-filterable-field-table > thead tr > th:nth-child(2) {
86+
text-align: center !important;
87+
}

‎docs/templates/layout.html

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{% extends "!layout.html" %}
2+
{% block extrahead %}
3+
<meta http-equiv="cache-control" content="max-age=60">
4+
{% endblock %}

‎linodecli/baked/operation.py

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,9 @@ def __init__(
361361
self.action = action
362362

363363
self.summary = operation.summary
364-
self.description = operation.description.split(".")[0] + "."
364+
self.description_rich, self.description = process_arg_description(
365+
operation.description or ""
366+
)
365367

366368
# The apiVersion attribute should not be specified as a positional argument
367369
self.params = [
@@ -591,6 +593,10 @@ def _add_args_post_put(
591593
arg.item_type if arg.datatype == "array" else arg.datatype
592594
)
593595

596+
# # TODO: Remove this workaround once the LKE docs issue has been resolved
597+
if arg_type is None:
598+
arg_type = "object"
599+
594600
arg_type_handler = TYPES[arg_type]
595601

596602
if arg.nullable:

‎linodecli/baked/parsing.py

Lines changed: 26 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@
55
import functools
66
import re
77
from html import unescape
8-
from typing import List, Tuple
8+
from typing import List, Optional, Tuple
99

1010
# Sentence delimiter, split on a period followed by any type of
1111
# whitespace (space, new line, tab, etc.)
12-
REGEX_SENTENCE_DELIMITER = re.compile(r"\.(?:\s|$)")
12+
REGEX_SENTENCE_DELIMITER = re.compile(r"\.(?:\s|$)", flags=re.M)
1313

1414
# Matches on pattern __prefix__ at the beginning of a description
1515
# or after a comma
16-
REGEX_TECHDOCS_PREFIX = re.compile(r"(?:, |\A)__([\w-]+)__")
16+
REGEX_TECHDOCS_PREFIX = re.compile(r"(?:, |\A)__([^_]+)__")
1717

1818
# Matches on pattern [link title](https://.../)
1919
REGEX_MARKDOWN_LINK = re.compile(r"\[(?P<text>.*?)]\((?P<link>.*?)\)")
@@ -121,23 +121,35 @@ def get_short_description(description: str) -> str:
121121
:rtype: set
122122
"""
123123

124-
target_lines = description.splitlines()
125-
relevant_lines = None
126-
127-
for i, line in enumerate(target_lines):
124+
def __simplify(sentence: str) -> Optional[str]:
128125
# Edge case for descriptions starting with a note
129-
if line.lower().startswith("__note__"):
130-
continue
126+
if sentence.lower().startswith("__note__"):
127+
return None
128+
129+
sentence = strip_techdocs_prefixes(sentence)
131130

132-
relevant_lines = target_lines[i:]
133-
break
131+
# Check that the sentence still has content after stripping prefixes
132+
if len(sentence) < 2:
133+
return None
134134

135-
if relevant_lines is None:
135+
return sentence + "."
136+
137+
# Find the first relevant sentence
138+
result = next(
139+
simplified
140+
for simplified in iter(
141+
__simplify(sentence)
142+
for sentence in REGEX_SENTENCE_DELIMITER.split(description)
143+
)
144+
if simplified is not None
145+
)
146+
147+
if result is None:
136148
raise ValueError(
137149
f"description does not contain any relevant lines: {description}",
138150
)
139151

140-
return REGEX_SENTENCE_DELIMITER.split("\n".join(relevant_lines), 1)[0] + "."
152+
return result
141153

142154

143155
def strip_techdocs_prefixes(description: str) -> str:
@@ -150,11 +162,7 @@ def strip_techdocs_prefixes(description: str) -> str:
150162
:returns: The stripped description
151163
:rtype: str
152164
"""
153-
result_description = REGEX_TECHDOCS_PREFIX.sub(
154-
"", description.lstrip()
155-
).lstrip()
156-
157-
return result_description
165+
return REGEX_TECHDOCS_PREFIX.sub("", description.lstrip()).lstrip()
158166

159167

160168
def process_arg_description(description: str) -> Tuple[str, str]:
@@ -173,7 +181,6 @@ def process_arg_description(description: str) -> Tuple[str, str]:
173181
return "", ""
174182

175183
result = get_short_description(description)
176-
result = strip_techdocs_prefixes(result)
177184
result = result.replace("\n", " ").replace("\r", " ")
178185

179186
# NOTE: Links should only be separated from Rich Markdown links

‎linodecli/baked/request.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,9 @@ def __init__(
105105
#: Whether null is an acceptable value for this attribute
106106
self.nullable = schema.nullable
107107

108+
#: An example value for this attribute
109+
self.example = schema.example
110+
108111
# handle the type for list values if this is an array
109112
if self.datatype == "array" and schema.items:
110113
self.item_type = schema.items.type

‎linodecli/baked/response.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,17 @@ def __init__(self, name, schema, prefix=None, nested_list_depth=0):
8080
#: How we should associate values of this attribute to output colors
8181
self.color_map = schema.extensions.get("linode-cli-color")
8282

83+
#: An example value for this attribute.
84+
self.example = schema.example
85+
8386
#: The type for items in this attribute, if this attribute is a list
8487
self.item_type = None
8588
if schema.type == "array":
8689
self.item_type = schema.items.type
8790

91+
if schema.items.example:
92+
self.example = schema.items.example
93+
8894
@property
8995
def path(self):
9096
"""

‎linodecli/documentation/generator.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
from jinja2 import Environment, PackageLoader, select_autoescape
1010

11-
from linodecli import CLI
11+
from linodecli.cli import CLI
1212
from linodecli.documentation.template_data import BuildMeta, Root
1313

1414
TEMPLATE_NAME_GROUP = "group.rst.j2"
@@ -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,

0 commit comments

Comments
 (0)