Various CI changes

linode · Sep 3, 2024 · c4da9d4 · c4da9d4
1 parent a664501
commit c4da9d4
Show file tree

Hide file tree

Showing 24 changed files with 569 additions and 80,840 deletions.
diff --git a/.github/workflows/publish-docs.yml → .github/workflows/documentation.yml b/.github/workflows/publish-docs.yml → .github/workflows/documentation.yml
@@ -13,7 +13,7 @@ on:
 
 jobs:
  build:
- name: Build the documentation
+ name: Build
  runs-on: ubuntu-latest
  steps:
  - name: Checkout repository
@@ -73,19 +73,18 @@ jobs:
  name: generated-docs-html
  path: docs/build/html
 
- publish:
- name: Publish the documentation
+ pages-commit:
+ name: Commit to Pages Branch
  runs-on: ubuntu-latest
  needs:
  - build
  # Make sure we avoid a race condition =)
  concurrency:
- group: "pages"
+ group: "docs-stage"
  cancel-in-progress: false
  permissions:
  contents: write
- pages: write
- id-token: write
+
  if: (github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'dev' || github.ref_name == 'new/doc-generation' )) || (github.ref_type == 'tag')
  steps:
  - name: Checkout the documentation branch
@@ -101,37 +100,52 @@ jobs:
  if: "${{ steps.checkout-docs.outcome != 'success' }}"
  run: git switch --orphan static/docs
 
- - name: Ensure any previous documentation for this branch are removed
+ - name: Ensure any previous documentation for this branch is removed
  run: rm -rf "./${{ github.ref_name }}"
 
- - name: Download the artifact from the previous job
+ - name: Download the artifact from the build job
  uses: actions/download-artifact@v4
  with:
  name: generated-docs-html
  path: "${{ github.ref_name }}"
 
  - name: Override the latest version if necessary
- if: ${{ github.event_name == 'release' }}
+ if: ${{ github.ref_type == 'tag' }}
  run: |
  rm -rf latest && cp -r ${{ github.ref_name }} latest
 
+ - name: Overlay static files
+ run: |
+ echo "<head><meta http-equiv='refresh' content='0; URL=latest/index.html'></head>" > index.html;
+ touch .nojekyll
+
  - name: Commit and push this change
  run: |
  git config user.name "Documentation Publisher";
  git config user.email "[email protected]";
  git add .;
- git commit --allow-empty -m "Rebuild ${{ github.ref_name }} from ${{ github.sha }}";
+ git commit --allow-empty -m "Build ${{ github.ref_name }} from ${{ github.sha }}";
  git push origin static/docs;
 
- - name: Configure GitHub Pages
- uses: actions/configure-pages@v5
+ upload-release-asset:
+ name: Upload Release Asset
+ runs-on: ubuntu-latest
+ needs:
+ - build
+ if: github.ref_type == 'tag'
+ steps:
+ - name: Download the artifact from the previous job
+ uses: actions/download-artifact@v4
  with:
- enablement: true
+ name: generated-docs-html
+ path: ".build/${{ github.ref_name }}"
 
- - name: Push the rendered documentation site to GitHub Pages
- uses: actions/upload-pages-artifact@v3
- with:
- path: .
+ - name: Archive the built documentation
+ run: |
+ cd .build/${{ github.ref_name }} && tar -czvf ../documentation.tar.gz *
 
- - name: Deploy to GitHub Pages
- uses: actions/deploy-pages@v4
+ - name: Upload the documentation as a release asset
+ uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191
+ with:
+ files: .build/documentation.tar.gz
+ tag_name: ${{ github.ref_name }}
diff --git a/Makefile b/Makefile
@@ -9,9 +9,6 @@ ifdef TEST_CASE
 TEST_CASE_COMMAND = -k $(TEST_CASE)
 endif
 
-# TODO: Revert this once the corrected spec is available.
-SPEC := ./openapi.yaml.tmp
-
 SPEC_VERSION ?= latest
 ifndef SPEC
 override SPEC = $(shell ./resolve_spec_url ${SPEC_VERSION})

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,14 +1,14 @@
-linode-cli Documentation
-========================
-
-.. image:: static/demo.gif
- :alt: Linode CLI Demo
+linode-cli
+==========
 
 Welcome to the `linode-cli` documentation!
 
 For installation instructions and usage guides, please
 refer to the sidebar of this page or the Table of Contents below.
 
+.. image:: static/demo.gif
+ :alt: Linode CLI Demo
+
 Table of Contents
 -----------------
 

diff --git a/docs/static/overlay.css b/docs/static/overlay.css
@@ -22,16 +22,66 @@ td {
  width: 150px !important;
 }
 
-/* Custom formatting for actions */
+/*
+Custom formatting for actions
+*/
 .action-subheading {
  margin-bottom: 4px !important;
+ font-weight: 700 !important;
 }
 
 .action-subheading-description {
  font-size: 90% !important;
  margin-bottom: 12px !important;
 }
 
-.action-argument-required {
- color: red !important;
+.action-section-header {
+ color: #606060 !important;
+ font-weight: 700 !important;
+ padding-top: 10px !important;
+ margin-bottom: 12px !important;
+ font-size: 95% !important;
+}
+
+.action-table-field-name,
+.action-table-field-optional,
+.action-table-field-required,
+.action-table-field-type {
+ font-size: 85% !important;
+ font-family: SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace !important;
+}
+
+.action-table-field-required {
+ color: #E74C3C !important;
+}
+
+/*
+Formatting for generated tables
+*/
+
+/* Prevent word wrapping on `Name` and `Example` 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) *,
+.action-attribute-section-table > tbody tr > td:nth-child(1) *,
+.action-attribute-section-table > tbody tr > td:nth-child(3) * {
+ 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-attribute-section-table > tbody tr > td:nth-child(2),
+.action-attribute-section-table > thead tr > th:nth-child(2),
+
+.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;
+}
diff --git a/docs/templates/layout.html b/docs/templates/layout.html
@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+ <meta http-equiv="cache-control" content="max-age=60">
+{% endblock %}
diff --git a/linodecli/baked/operation.py b/linodecli/baked/operation.py
@@ -361,7 +361,9 @@ def __init__(
  self.action = action
 
  self.summary = operation.summary
- self.description = operation.description.split(".")[0] + "."
+ self.description_rich, self.description = process_arg_description(
+ operation.description or ""
+ )
 
  # The apiVersion attribute should not be specified as a positional argument
  self.params = [
@@ -591,6 +593,10 @@ def _add_args_post_put(
  arg.item_type if arg.datatype == "array" else arg.datatype
  )
 
+ # # TODO: Remove this workaround once the LKE docs issue has been resolved
+ if arg_type is None:
+ arg_type = "object"
+
  arg_type_handler = TYPES[arg_type]
 
  if arg.nullable:

diff --git a/linodecli/baked/parsing.py b/linodecli/baked/parsing.py
@@ -5,15 +5,15 @@
 import functools
 import re
 from html import unescape
-from typing import List, Tuple
+from typing import List, Optional, Tuple
 
 # Sentence delimiter, split on a period followed by any type of
 # whitespace (space, new line, tab, etc.)
-REGEX_SENTENCE_DELIMITER = re.compile(r"\.(?:\s|$)")
+REGEX_SENTENCE_DELIMITER = re.compile(r"\.(?:\s|$)", flags=re.M)
 
 # Matches on pattern __prefix__ at the beginning of a description
 # or after a comma
-REGEX_TECHDOCS_PREFIX = re.compile(r"(?:, |\A)__([\w-]+)__")
+REGEX_TECHDOCS_PREFIX = re.compile(r"(?:, |\A)__([^_]+)__")
 
 # Matches on pattern [link title](https://.../)
 REGEX_MARKDOWN_LINK = re.compile(r"\[(?P<text>.*?)]\((?P<link>.*?)\)")
@@ -121,23 +121,35 @@ def get_short_description(description: str) -> str:
  :rtype: set
  """
 
- target_lines = description.splitlines()
- relevant_lines = None
-
- for i, line in enumerate(target_lines):
+ def __simplify(sentence: str) -> Optional[str]:
  # Edge case for descriptions starting with a note
- if line.lower().startswith("__note__"):
- continue
+ if sentence.lower().startswith("__note__"):
+ return None
+
+ sentence = strip_techdocs_prefixes(sentence)
 
- relevant_lines = target_lines[i:]
- break
+ # Check that the sentence still has content after stripping prefixes
+ if len(sentence) < 2:
+ return None
 
- if relevant_lines is None:
+ return sentence + "."
+
+ # Find the first relevant sentence
+ result = next(
+ simplified
+ for simplified in iter(
+ __simplify(sentence)
+ for sentence in REGEX_SENTENCE_DELIMITER.split(description)
+ )
+ if simplified is not None
+ )
+
+ if result is None:
  raise ValueError(
  f"description does not contain any relevant lines: {description}",
  )
 
- return REGEX_SENTENCE_DELIMITER.split("\n".join(relevant_lines), 1)[0] + "."
+ return result
 
 
 def strip_techdocs_prefixes(description: str) -> str:
@@ -150,11 +162,7 @@ def strip_techdocs_prefixes(description: str) -> str:
  :returns: The stripped description
  :rtype: str
  """
- result_description = REGEX_TECHDOCS_PREFIX.sub(
- "", description.lstrip()
- ).lstrip()
-
- return result_description
+ return REGEX_TECHDOCS_PREFIX.sub("", description.lstrip()).lstrip()
 
 
 def process_arg_description(description: str) -> Tuple[str, str]:
@@ -173,7 +181,6 @@ def process_arg_description(description: str) -> Tuple[str, str]:
  return "", ""
 
  result = get_short_description(description)
- result = strip_techdocs_prefixes(result)
  result = result.replace("\n", " ").replace("\r", " ")
 
  # NOTE: Links should only be separated from Rich Markdown links

diff --git a/linodecli/baked/request.py b/linodecli/baked/request.py
@@ -105,6 +105,9 @@ def __init__(
  #: Whether null is an acceptable value for this attribute
  self.nullable = schema.nullable
 
+ #: An example value for this attribute
+ self.example = schema.example
+
  # handle the type for list values if this is an array
  if self.datatype == "array" and schema.items:
  self.item_type = schema.items.type

diff --git a/linodecli/baked/response.py b/linodecli/baked/response.py
@@ -80,11 +80,17 @@ def __init__(self, name, schema, prefix=None, nested_list_depth=0):
  #: How we should associate values of this attribute to output colors
  self.color_map = schema.extensions.get("linode-cli-color")
 
+ #: An example value for this attribute.
+ self.example = schema.example
+
  #: The type for items in this attribute, if this attribute is a list
  self.item_type = None
  if schema.type == "array":
  self.item_type = schema.items.type
 
+ if schema.items.example:
+ self.example = schema.items.example
+
  @property
  def path(self):
  """

diff --git a/linodecli/documentation/generator.py b/linodecli/documentation/generator.py
@@ -8,7 +8,7 @@
 
 from jinja2 import Environment, PackageLoader, select_autoescape
 
-from linodecli import CLI
+from linodecli.cli import CLI
 from linodecli.documentation.template_data import BuildMeta, Root
 
 TEMPLATE_NAME_GROUP = "group.rst.j2"
@@ -25,6 +25,7 @@ class DocumentationGenerator:
  def __init__(self):
  self._template_env = Environment(
  loader=PackageLoader("linodecli.documentation", "templates"),
+ extensions=["jinja2.ext.do"],
  autoescape=select_autoescape(),
  trim_blocks=True,
  lstrip_blocks=True,