new: Changes for CLI/TechDocs spec compatibility #624

lgarber-akamai · 2024-07-02T16:32:59Z

📝 Description

This pull request resolves a few issues in the OpenAPI spec generation/baking logic that prevented it from being compatible with the upcoming new TechDocs OpenAPI spec. The changes in this PR were also made to be backwards compatible to make sure the transition between specs goes smoothly 🙂

Because this PR needed to be all-encompassing, it also includes a bunch of minor fixes that should get previously failing integration tests passing.

Additionally this PR requires a few minor changes to the internal documentation linked in TPT-3016.

✔️ How to Test

NOTE: You will need to opt into Linode Managed for the managed-related tests to pass. If you would like to subsequently opt-out of Linode Managed, see the description of TPT-3016.

The following test steps assume you have pulled down this PR locally.

Building & Installing the CLI

With the TechDocs OpenAPI Spec

Download the (modified) new OpenAPI spec YAML file to openapi-techdocs.yaml (see TPT-3016's description).
Install the local version of the CLI using the new spec file:

make SPEC=$PWD/openapi-techdocs.yaml install

From here you should be able to run and test arbitrary commands using linode-cli.

With the Legacy (linode-api-docs) OpenAPI Spec

Install the local version of the CLI without specifying the SPEC argument:

make install

From here you should be able to run and test arbitrary commands using linode-cli.

Integration Testing

NOTE: This test command should be run for both versions of the CLI installed above.

make testint

NOTE: The following tests are expected to fail when running against the legacy spec due to bug fixes that were only applied to the TechDocs spec:

account/test_account.py::test_user_view

Unit Testing

make testunit

lgarber-akamai · 2024-07-03T21:37:14Z

linodecli/output/output_handler.py

+                    # matches the path of this column
+                    if col == attr.name:


Breaking change to resolve the following from giving an unexpected placement_group.id output:

linode-cli linodes ls --format id

I would consider the previous functionality to technically be broken so I'm thinking this change might be for the best in the long run. If we do end up making this change, we should definitely communicate it through our release notes (and maybe add a warning)?

If anyone else has any ideas definitely let me know 🙂

See: https://github.com/linode/linode-cli/pull/624/files#r1664858657

lgarber-akamai · 2024-07-03T21:38:35Z

tests/integration/account/test_account.py

@@ -244,7 +244,7 @@ def get_user_id():
                "--delimiter",
                ",",
                "--format",
-                "id",
+                "username",


This test passed at some point because a --format string with an invalid field will give all of the results starting with username. This doesn't seem to be the case anymore so I adjusted it accordingly 👍

lgarber-akamai · 2024-07-03T21:39:17Z

tests/integration/cli/test_help.py

+            "API Documentation:  https://www.linode.com/docs/api/linode-instances/#linodes-list",
+            "API Documentation:  https://www.linode.com/docs/api/linode-instances/#list-linodes",


There are some minor (but valid) changes to the help pages/descriptions for certain endpoint methods. I updated the tests accordingly to ensure everything will be backwards compatible

lgarber-akamai · 2024-07-03T22:00:33Z

tests/integration/helpers.py

@@ -34,7 +39,9 @@ def exec_test_command(args: List[str]):
    return process


-def exec_failing_test_command(args: List[str], expected_code: int = 1):
+def exec_failing_test_command(
+    args: List[str], expected_code: int = ExitCodes.REQUEST_FAILED


Inherited from #625

lgarber-akamai · 2024-07-03T22:01:00Z

tests/integration/linodes/test_backups.py

@@ -73,7 +73,7 @@ def test_create_linode_with_backup_disabled(
            "list",
            "--id",
            linode_id,
-            "--format=id,enabled",
+            "--format=id,backups.enabled",


This is the effect of the breaking change mentioned above

ezilber-akamai

Everything is working as intended. Nice work!

linodecli/helpers.py

zliang-akamai

Tests work well! Just a minor typing suggestion, otherwise looks great!

Co-authored-by: Zhiwei Liang <[email protected]>

yec-akamai

Tested discovered issues work perfectly now. Great work!

lgarber-akamai · 2024-07-17T15:02:24Z

linodecli/baked/parsing.py

+# Matches on pattern [link title](https://.../)
+REGEX_MARKDOWN_LINK = re.compile(r"\[(?P<text>.*?)]\((?P<link>.*?)\)")
+
+MARKDOWN_RICH_TRANSLATION = [


I was originally trying to use the Rich Markdown renderable but there were a bunch of small issues relating to grouping and styles that heavily complicated things. For the time being this should work 🙂

lgarber-akamai · 2024-07-17T15:03:56Z

linodecli/baked/request.py

+        description_rich, description = process_arg_description(
+            schema.description or ""
        )

+        #: The description of this argument for Markdown/plaintext display
+        self.description = description
+
+        #: The description of this argument for display on the help page
+        self.description_rich = description_rich


We're now baking the rendered descriptions directly into the request for re-use and optimization purposes.

NOTE: The description field is preserved here in preparation for potential docs generation down the road.

lgarber-akamai · 2024-07-17T15:05:08Z

linodecli/baked/parsing.py

+    def _sub_handler(match: re.Match) -> str:
+        link = match["link"]
+        if link.startswith("/"):
+            link = f"https://linode.com{link}"


The TechDocs spec does not use relative paths so this is necessary to maintain for backwards compatibility purposes

lgarber-akamai · 2024-07-17T15:45:44Z

linodecli/baked/parsing.py

+    description, links = extract_markdown_links(result)
+
+    if len(links) > 0:
+        description += f" See: {'; '.join(links)}"


Links are now extracted and appended to the end of an argument's description:

--region (required): The region where the Linode will be located. See: https://techdocs.akamai.com/linode-api/reference/get-regions

Previously links were embedded inline after the display text, but this made thing super unreadable with TechDocs due to long the new URLs are.

ykim-akamai

LGTM, integration tests and reported issues verified locally. Nice work!

Resolve issues blocking CLI/TechDocs OpenAPI spec compatibility

31af357

lgarber-akamai added bugfix for any bug fixes in the changelog. improvement for improvements in existing functionality in the changelog. and removed bugfix for any bug fixes in the changelog. labels Jul 2, 2024

lgarber-akamai changed the title ~~fix: Resolve issues blocking CLI/TechDocs OpenAPI spec compatibility~~ new: Resolve issues blocking CLI/TechDocs OpenAPI spec compatibility Jul 2, 2024

lgarber-akamai changed the title ~~new: Resolve issues blocking CLI/TechDocs OpenAPI spec compatibility~~ new: Changes for CLI/TechDocs spec compatibility Jul 2, 2024

lgarber-akamai commented Jul 3, 2024

View reviewed changes

lgarber-akamai marked this pull request as ready for review July 3, 2024 21:42

lgarber-akamai requested a review from a team as a code owner July 3, 2024 21:42

lgarber-akamai requested review from jriddle-linode and ezilber-akamai and removed request for a team July 3, 2024 21:42

lgarber-akamai commented Jul 3, 2024

View reviewed changes

Add CLI compatibility for TechDocs spec; fix failing integration tests

630e434

lgarber-akamai force-pushed the fix/cli-new-spec-compat branch from 38abfbb to 630e434 Compare July 5, 2024 14:05

This comment was marked as outdated.

Sign in to view

lgarber-akamai requested a review from ezilber-akamai July 5, 2024 15:37

ezilber-akamai approved these changes Jul 5, 2024

View reviewed changes

lgarber-akamai requested review from a team, zliang-akamai, ykim-akamai and yec-akamai and removed request for a team July 5, 2024 17:46

Fix merge conflicts

53026c5

zliang-akamai reviewed Jul 11, 2024

View reviewed changes

linodecli/helpers.py Outdated Show resolved Hide resolved

zliang-akamai approved these changes Jul 11, 2024

View reviewed changes

Update linodecli/helpers.py

4740a94

Co-authored-by: Zhiwei Liang <[email protected]>

Import Optional in helpers.py

b9dd336

lgarber-akamai force-pushed the fix/cli-new-spec-compat branch from 2024ba4 to 1677e08 Compare July 17, 2024 14:06

Add parsing package

621c928

lgarber-akamai force-pushed the fix/cli-new-spec-compat branch from 1677e08 to 621c928 Compare July 17, 2024 14:09

Fix ticket test

13347a3

yec-akamai approved these changes Jul 17, 2024

View reviewed changes

Disable betas test if no betas are found

ba04c97

lgarber-akamai commented Jul 17, 2024

View reviewed changes

lgarber-akamai added 3 commits July 17, 2024 13:28

Fix operation-level docs URLs

434104c

Make filterable attributes color consistent

bb72a31

Fix help integration tests

bbe41f7

ykim-akamai approved these changes Jul 17, 2024

View reviewed changes

lgarber-akamai merged commit 3be330c into linode:dev Jul 17, 2024
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

new: Changes for CLI/TechDocs spec compatibility #624

new: Changes for CLI/TechDocs spec compatibility #624

lgarber-akamai commented Jul 2, 2024 •

edited

Loading

lgarber-akamai Jul 3, 2024 •

edited

Loading

lgarber-akamai Jul 3, 2024 •

edited

Loading

lgarber-akamai Jul 3, 2024

lgarber-akamai Jul 3, 2024

lgarber-akamai Jul 3, 2024

This comment was marked as outdated.

ezilber-akamai left a comment

zliang-akamai left a comment

yec-akamai left a comment

lgarber-akamai Jul 17, 2024

lgarber-akamai Jul 17, 2024

lgarber-akamai Jul 17, 2024

lgarber-akamai Jul 17, 2024

ykim-akamai left a comment

		"API Documentation: https://www.linode.com/docs/api/linode-instances/#linodes-list",
		"API Documentation: https://www.linode.com/docs/api/linode-instances/#list-linodes",

new: Changes for CLI/TechDocs spec compatibility #624

new: Changes for CLI/TechDocs spec compatibility #624

Conversation

lgarber-akamai commented Jul 2, 2024 • edited Loading

📝 Description

✔️ How to Test

Building & Installing the CLI

With the TechDocs OpenAPI Spec

With the Legacy (linode-api-docs) OpenAPI Spec

Integration Testing

Unit Testing

lgarber-akamai Jul 3, 2024 • edited Loading

Choose a reason for hiding this comment

lgarber-akamai Jul 3, 2024 • edited Loading

Choose a reason for hiding this comment

lgarber-akamai Jul 3, 2024

Choose a reason for hiding this comment

lgarber-akamai Jul 3, 2024

Choose a reason for hiding this comment

lgarber-akamai Jul 3, 2024

Choose a reason for hiding this comment

This comment was marked as outdated.

ezilber-akamai left a comment

Choose a reason for hiding this comment

zliang-akamai left a comment

Choose a reason for hiding this comment

yec-akamai left a comment

Choose a reason for hiding this comment

lgarber-akamai Jul 17, 2024

Choose a reason for hiding this comment

lgarber-akamai Jul 17, 2024

Choose a reason for hiding this comment

lgarber-akamai Jul 17, 2024

Choose a reason for hiding this comment

lgarber-akamai Jul 17, 2024

Choose a reason for hiding this comment

ykim-akamai left a comment

Choose a reason for hiding this comment

lgarber-akamai commented Jul 2, 2024 •

edited

Loading

lgarber-akamai Jul 3, 2024 •

edited

Loading

lgarber-akamai Jul 3, 2024 •

edited

Loading