DOCS-1088: Document more of the cloud API #1814

JessamyT · 2023-09-12T21:26:12Z

Code examples have all been tested (with valid strings of course)

viambot · 2023-09-12T21:27:14Z

Overall readability score: 54.78 (🟢 +0.08)

File	Readability
cloud.md	54.2 (🟢 +4.7)
cloud.md	74.85 (🟢 +21.3)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
cloud.md	54.2	30.36	7.97	16.7	14.96	5.75
	🟢 +4.7	🟢 +0.2	🟢 +1.64	🔴 -1	🔴 -0.46	🟢 +1.23
cloud.md	74.85	39.09	6.62	7.2	9.87	7.02
	🟢 +21.3	🟢 +9.37	🟢 +2.65	🟢 +2.8	🟢 +3.66	🟢 +1.86

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	54.78	46.21	10.86	13.31	11.81	7.76
	🟢 +0.08	🟢 +0.03	🟢 +0.01	🟢 +0.01	🟢 +0.01	🟢 +0.01

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

sguequierre

Couple typos and clarity suggestions. Thank you for taking this on!!

docs/program/apis/cloud.md

sguequierre · 2023-09-13T18:32:20Z

docs/program/apis/cloud.md

+
+### UpdateLocation
+
+Change the name of a {{< glossary_tooltip term_id="location" text="parent location" >}} and/or assign it a new location.


Not sure if it's ok to use and/or generally with current style guidance, but I can't think of a better way to phrase it 😆 So my thought is it's ok?

Yeah I had the same thought :D So I just left it as it was in the Python docs

sguequierre · 2023-09-13T18:33:28Z

docs/program/apis/cloud.md

+- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The newly updated location.
+
+```python {class="line-numbers linkable-line-numbers"}
+# The following line takes the location with ID "abc12abcde" and moves it


Suggested change

# The following line takes the location with ID "abc12abcde" and moves it

# The following line takes the location with ID "abc12abcde" and moves it to be a sub-location of the location with ID "xyz34xxxxx"

(opt) Would put this all on one line myself bc I personally think it looks better, but highly highly optional

I think I'll leave as-is because on narrow screens it will become quite wide. However, maybe I should split the parameters onto multiple lines as well now that I look at it...

(done splitting BTW)

sguequierre · 2023-09-13T18:33:34Z

docs/program/apis/cloud.md

+
+```python {class="line-numbers linkable-line-numbers"}
+# The following line takes the location with ID "abc12abcde" and moves it
+# to be a sub-location of the location with ID "xyz34xxxxx"


Suggested change

# to be a sub-location of the location with ID "xyz34xxxxx"

sguequierre · 2023-09-13T18:33:53Z

docs/program/apis/cloud.md

+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete.


Suggested change

- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete.

- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location.

(opt)

Possibly superfluous but leaving as-is just to make sure they get it and don't somehow think it's the parent location or some such, and because this is a very short description anyway so I'm not too worried about verbosity here.

docs/program/apis/cloud.md

sguequierre · 2023-09-13T19:07:05Z

docs/program/apis/cloud.md

+
+**Returns:**
+
+- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID.


Suggested change

- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID.

- [(Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID.

I'm actually not super sure if this is best but generally bc they're using this package I would remove the rest of the import, as they won't really need it to understand their code and it's linked

sguequierre

lgtm docs writing wise and code sample wise, would suggest getting another approval from Andrew or Naomi

sguequierre · 2023-09-13T19:11:54Z

docs/program/apis/cloud.md

+
+### LocationAuth
+
+Get a location’s `LocationAuth` (location secret or secrets).


Suggested change

Get a location’s `LocationAuth` (location secret or secrets).

Get a location’s location secret by ID.

Sorry, I know I approved already, but I think specifying by ID in description is good and would remove parenthesis. Optional but strongly suggest

Hmm the LocationAuth isn't just the location secret; it also contains location ID and secret IDs. How about this

Suggested change

Get a location’s `LocationAuth` (location secret or secrets).

Get a location’s authentication information by location ID.

docs/program/apis/cloud.md

stuqdog · 2023-09-13T20:18:42Z

docs/program/apis/cloud.md

+- None
+
+```python {class="line-numbers linkable-line-numbers"}
+# Replace string with a valid location ID


there are a lot of fake location IDs in here but I don't think this advisory comment appears in all of them. Would it make sense to either remove it here, or add it everywhere else that we have a fake location_id?

You're not wrong; I should probably just remove them all

Removed them all!

Co-authored-by: Sierra Guequierre <[email protected]>

stuqdog

One small thing (no need to rerequest review) otherwise lgtm!

docs/program/apis/cloud.md

viambot · 2023-09-14T14:45:59Z

You can view a rendered version of the docs from this PR at https://docs-test.viam.dev/bece4aadcb1873bc7ff4a57da6bc020468d3df23/public

viambot added the safe to build This pull request is marked safe to build from a trusted zone label Sep 12, 2023

JessamyT requested a review from stuqdog September 13, 2023 18:17

sguequierre reviewed Sep 13, 2023

View reviewed changes

JessamyT commented Sep 13, 2023

View reviewed changes

docs/program/apis/cloud.md Outdated Show resolved Hide resolved

JessamyT commented Sep 13, 2023

View reviewed changes

docs/program/apis/cloud.md Outdated Show resolved Hide resolved

JessamyT commented Sep 13, 2023

View reviewed changes

docs/program/apis/cloud.md Outdated Show resolved Hide resolved

JessamyT requested a review from sguequierre September 13, 2023 18:54

sguequierre reviewed Sep 13, 2023

View reviewed changes

sguequierre approved these changes Sep 13, 2023

View reviewed changes

sguequierre reviewed Sep 13, 2023

View reviewed changes

JessamyT commented Sep 13, 2023

View reviewed changes

docs/program/apis/cloud.md Outdated Show resolved Hide resolved

stuqdog reviewed Sep 13, 2023

View reviewed changes

JessamyT and others added 10 commits September 13, 2023 16:42

DOCS-1088: Add more cloud API methods

b723945

change

b4dfe71

Add more methods

90b62c7

add through get_robot

702d255

remove extra newline

78ef877

Fix code samples and arg names per testing

afbeb50

remove trailing space

83e0505

Apply suggestions from code review

0f7116d

Co-authored-by: Sierra Guequierre <[email protected]>

Update docs/program/apis/cloud.md

f0acac3

remove comments about fake location IDs

f1bdcb9

JessamyT force-pushed the 1088cloud branch from 5abb867 to f1bdcb9 Compare September 13, 2023 20:45

JessamyT requested a review from stuqdog September 13, 2023 20:46

stuqdog approved these changes Sep 14, 2023

View reviewed changes

docs/program/apis/cloud.md Outdated Show resolved Hide resolved

Apply suggestions from code review

bece4aa

JessamyT merged commit 7d1fbed into viamrobotics:main Sep 14, 2023

JessamyT deleted the 1088cloud branch September 14, 2023 15:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS-1088: Document more of the cloud API #1814

DOCS-1088: Document more of the cloud API #1814

JessamyT commented Sep 12, 2023 •

edited

Loading

viambot commented Sep 12, 2023 •

edited

Loading

sguequierre left a comment

sguequierre Sep 13, 2023

JessamyT Sep 13, 2023

sguequierre Sep 13, 2023

JessamyT Sep 13, 2023

JessamyT Sep 13, 2023

sguequierre Sep 13, 2023

sguequierre Sep 13, 2023

JessamyT Sep 13, 2023

sguequierre Sep 13, 2023

sguequierre left a comment

sguequierre Sep 13, 2023

JessamyT Sep 13, 2023

stuqdog Sep 13, 2023

JessamyT Sep 13, 2023

JessamyT Sep 13, 2023

stuqdog left a comment

viambot commented Sep 14, 2023


		### UpdateLocation

		Change the name of a {{< glossary_tooltip term_id="location" text="parent location" >}} and/or assign it a new location.

	# The following line takes the location with ID "abc12abcde" and moves it
	# The following line takes the location with ID "abc12abcde" and moves it to be a sub-location of the location with ID "xyz34xxxxx"


		Parameters:

		- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete.


		Returns:

		- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID.

	- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID.
	- [(Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID.


		### LocationAuth

		Get a location’s `LocationAuth` (location secret or secrets).

	Get a location’s `LocationAuth` (location secret or secrets).
	Get a location’s location secret by ID.

	Get a location’s `LocationAuth` (location secret or secrets).
	Get a location’s authentication information by location ID.

DOCS-1088: Document more of the cloud API #1814

DOCS-1088: Document more of the cloud API #1814

Conversation

JessamyT commented Sep 12, 2023 • edited Loading

viambot commented Sep 12, 2023 • edited Loading

sguequierre left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sguequierre left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stuqdog left a comment

Choose a reason for hiding this comment

viambot commented Sep 14, 2023

JessamyT commented Sep 12, 2023 •

edited

Loading

viambot commented Sep 12, 2023 •

edited

Loading