api-docs: Update usage examples for stream to channel rename.

[laurynmm]

Updates the Python and Javascript usage examples in the API documentation for the stream to channel rename.

Notes:

• Focuses on updating descriptive text as function, endpoint and parameter/field names would be separate API changes if/when we decide to make them.
• Updates some example strings used for channel names and some variable names.
• For some Python usage examples, shows getting the value for a request field/parameter to improve clarity of example.

Example screenshots:

Get channel/stream ID endpoint

Current documentation

Update channel/stream enpoint

Current documentation

Update personal preferences for topic endpoint

Current documentation

---

Self-review checklist

• Self-reviewed the changes for clarity and maintainability
  (variable names, code reuse, readability, etc.).

Communicate decisions, questions, and potential concerns.

• Explains differences from previous plans (e.g., issue description).
• Highlights technical choices and bugs encountered.
• Calls out remaining decisions and concerns.
• Automated tests verify logic where appropriate.

Individual commits are ready for review (see commit discipline).

• Each commit is a coherent idea.
• Commit message(s) explain reasoning and motivation for changes.

Completed manual review and testing of the following:

• Visual appearance of the changes.
• Responsiveness and internationalization.
• Strings and tooltips.
• End-to-end functionality of buttons, interactions and flows.
• Corner cases, error conditions, and easily imagined bugs.

[laurynmm]

Updates:

• Removed any changes that updated any of the Python usage examples to show getting a value (e.g. a channel ID) for a variable that's passed to the code example.
• Made some revisions to some of the descriptive comments in the Python usage examples.

Updated screenshots:

Get channel/stream ID endpoint

Current documentation

Update a channel/stream endpoint

Current documentation

Update personal preferences for a topic endpoint

Current documentation

Not changed

• Various Python usage examples have a stream_id variable that's used for the code example. It's possible that we want to update those to channel_id, but that could be confusing as the parameter named in the documentation is still uses "stream". See the example screenshots above for "Update a channel/stream" and "Update personal preferences ..." as examples of the current state.

[zulipbot]

Hello @zulip/server-api members, this pull request was labeled with the "area: documentation (api and integrations)" label, so you may want to check it out!

[timabbott]

Regarding those stream_id parameters, I think probably we can leave those for a future pass following renaming stuff in python-zulip-api (with compatibility support), since then we can also change the function names called.

[timabbott]

"to the channel"

[timabbott]

Made several copyediting changes along these lines:

diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py
index c268fe39e3..60552c5788 100644
--- a/zerver/openapi/python_examples.py
+++ b/zerver/openapi/python_examples.py
@@ -691,7 +691,7 @@ def get_streams(client: Client) -> None:
 @openapi_test_function("/streams/{stream_id}:patch")
 def update_stream(client: Client, stream_id: int) -> None:
     # {code_example|start}
-    # Update channel, with a given channel ID.
+    # Update settings for the channel with a given ID.
     request = {
         "stream_id": stream_id,
         "stream_post_policy": 2,
@@ -800,7 +800,7 @@ def toggle_mute_topic(client: Client) -> None:
     )
 
     # {code_example|start}
-    # Mute the topic "boat party" in channel named "Denmark".
+    # Mute the topic "boat party" in the channel named "Denmark".
     request = {
         "stream": "Denmark",
         "topic": "boat party",
@@ -812,7 +812,7 @@ def toggle_mute_topic(client: Client) -> None:
     validate_against_openapi_schema(result, "/users/me/subscriptions/muted_topics", "patch", "200")
 
     # {code_example|start}
-    # Unmute the topic "boat party" in channel named "Denmark".
+    # Unmute the topic "boat party" in the channel named "Denmark".
     request = {
         "stream": "Denmark",
         "topic": "boat party",
@@ -902,7 +902,7 @@ def mark_all_as_read(client: Client) -> None:
 @openapi_test_function("/mark_stream_as_read:post")
 def mark_stream_as_read(client: Client) -> None:
     # {code_example|start}
-    # Mark the unread messages in channel with ID 1 as read.
+    # Mark the unread messages in the channel with ID 1 as read.
     result = client.mark_stream_as_read(1)
     # {code_example|end}
 
@@ -964,7 +964,7 @@ def render_message(client: Client) -> None:
 def get_messages(client: Client) -> None:
     # {code_example|start}
     # Get the 100 last messages sent by "iago@zulip.com" to
-    # channel named "Verona".
+    # the channel named "Verona".
     request: Dict[str, Any] = {
         "anchor": "newest",
         "num_before": 100,
@@ -1475,7 +1475,7 @@ def set_typing_status(client: Client) -> None:
 
     # {code_example|start}
     # The user has started to type in topic "typing status"
-    # of channel named "Denmark".
+    # of the channel named "Denmark".
     stream_id = client.get_stream_id("Denmark")["stream_id"]
     topic = "typing status"
 
@@ -1493,7 +1493,7 @@ def set_typing_status(client: Client) -> None:
 
     # {code_example|start}
     # The user has finished typing in topic "typing status"
-    # of channel named "Denmark".
+    # of the channel named "Denmark".
     stream_id = client.get_stream_id("Denmark")["stream_id"]
     topic = "typing status"
 

[laurynmm]

Thanks for catching and updating those!

[timabbott]

Merged, after the small copyediting changes noted above, thanks @laurynmm!