add readme file #1387

hghalebi · 2025-02-27T18:07:03Z

Pull Request: Refactor Tutorial to Google Cloud Style Documentation

Description

This PR refactors the existing web tutorial to follow Google Cloud's documentation style guidelines, improving readability and usability for developers.

Changes Made

Restructured content to follow Google Cloud's progressive disclosure pattern
Added comprehensive authentication examples
Introduced detailed error handling patterns
Included troubleshooting section with common issues
Added clear setup instructions and prerequisites
Improved code examples with detailed comments
Added next steps and additional resources sections

Key Features

Authentication Examples
- Application Default Credentials (ADC)
- Service Account authentication
- Clear setup instructions
Error Handling
- Comprehensive error handling patterns
- Service error management
- Type-safe error handling examples
Long-running Operations
- Added examples for handling async operations
- Implemented backoff policies
- Proper operation management
Troubleshooting Guide
- Common authentication issues
- API enablement instructions
- Permission management

Testing Done

Verified all code examples compile
Tested documentation links
Validated markdown formatting
Ensured code snippets follow Rust best practices

Screenshots

N/A (Documentation changes only)

Related Issues

Closes #[issue_number] - Add Google Cloud style documentation

Checklist

Documentation follows Google Cloud style guide
Code examples are properly formatted and commented
All links are valid and working
Markdown syntax is correct
Examples include error handling
Prerequisites are clearly stated

Notes for Reviewers

Please pay special attention to:

Documentation flow and progression
Code example completeness
Error handling patterns
Authentication examples

google-cla · 2025-02-27T18:07:08Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

coryan · 2025-02-27T18:32:20Z

This change is really useful, thanks! Please sign the CLA and let us know, we cannot accept the change until then.

Do you think we should refactor this to a chapter in the User Guide (see guide/src for the source).

hghalebi · 2025-02-28T15:48:39Z

This change is really useful, thanks! Please sign the CLA and let us know, we cannot accept the change until then.

Do you think we should refactor this to a chapter in the User Guide (see guide/src for the source).

yes I do think we need documentation in tutorial style. And if you support I could try to contribute more in this way

hghalebi · 2025-02-28T15:53:31Z

i have tired to sign CLA but i got error:

coryan · 2025-02-28T17:52:58Z

i have tired to sign CLA but i got error:

I cannot find a place where either of us can file a bug or otherwise troubleshoot the problem. Best advice I can give you is to try again in a few hours or something.

hghalebi · 2025-03-05T09:57:51Z

i have tired to sign CLA but i got error:

I cannot find a place where either of us can file a bug or otherwise troubleshoot the problem. Best advice I can give you is to try again in a few hours or something.

I just sigh. @coryan

coryan · 2025-03-05T14:38:59Z

One thing of note, the PR includes contributions using two different emails:

Could you create a new PR with whatever email you used to sign the CLA (assuming you are able to sign the CLA at all).

If that does not work, we should close the PR. I think your idea would be valuable as a chapter in the book. Happy to do it ourselves.

hghalebi · 2025-03-06T20:11:45Z

I will retry this weekend ( Paris time zone). I hope that solves the issue. If not, you could add yourself directly. I will be more than happy to add more tutorial-style docs.

hghalebi · 2025-03-08T11:09:23Z

@coryan, I updated my CLA signature. Please recheck. If the issue is still present, please add it yourself the way that you prefer.

coryan · 2025-03-08T16:57:10Z

Looks much better. It seems that this PR is mixing two commits and the robots only recognize one for the CLA:

I can tell that this is a single author, but it would be nice if you can clean this up to make the merge easier.

In the interim, let me start reviewing this.

codecov · 2025-03-08T17:08:59Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.96%. Comparing base (dfcd1c4) to head (da8a2dd).
Report is 31 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1387   +/-   ##
=======================================
  Coverage   95.96%   95.96%           
=======================================
  Files          37       37           
  Lines        1462     1462           
=======================================
  Hits         1403     1403           
  Misses         59       59

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

coryan · 2025-03-08T17:01:06Z

tutorial.md

Let's move this file to guide/src/. I think we will need to break this down, you are covering too much ground for a single document.

First, the initialization of a simple client is already covered in "Setting up your development environment". We can probably skip that.

Second, the long running operations are already covered too, we can skip that.

We should use your example of how to initialize using service account credentials into a new chapter titled "Using service account credentials" (or something similar).

We should break the section on error handling to its own chapter also.

You will need to use mdformat to fix a number of formatting issues:

https://github.com/googleapis/google-cloud-rust/actions/runs/13572960728/job/38427364311?pr=1387

And need to rebase to get the latest build scripts going.

coryan · 2025-03-08T17:16:15Z

tutorial.md

+#### Listing secrets
+
+```rust
+use google_cloud_secretmanager_v1::client::SecretManagerServiceClient;


I think the client name is simply SecretManagerService. This is why we write the code samples as actual code in guide/samples/* and embed the code using {{#include }} to ensure the code actually compiles.

Please refactor all the code compilable code samples.

coryan · 2025-03-08T17:18:50Z

tutorial.md

+## Troubleshooting
+
+### Common issues
+


This is a really good idea.

coryan · 2025-03-08T17:20:08Z

tutorial.md

+2. **API not enabled**
+   - Enable the required APIs in your project:
+     ```bash
+     gcloud services enable secretmanager.googleapis.com


You are missing some APIs used above, like speech.googleapis.com. Keeping the tutorial focused on one topic makes it easier to catch these problems.

coryan · 2025-03-08T17:23:16Z

tutorial.md

+        .await?;
+
+    // Wait for completion
+    let result = operation.await_complete().await?;


I do not think this would compile.

coryan · 2025-03-08T17:24:06Z

tutorial.md

+Some Google Cloud operations may take a long time to complete. Here's how to handle them:
+
+```rust
+use google_cloud_speech_v2::client::SpeechClient;


The name of this client is incorrect again.

coryan · 2025-03-08T17:24:19Z

tutorial.md

+}
+```
+
+### Working with long-running operations


We have two tutorials dedicated to this:

https://googleapis.github.io/google-cloud-rust/working_with_long_running_operations.html
https://googleapis.github.io/google-cloud-rust/configuring_polling_policies.html

This seems redundant.

coryan · 2025-03-08T17:30:03Z

tutorial.md

+            Ok(())
+        }
+        Err(e) => {
+            if let Some(status) = e.downcast_ref::<ServiceError>() {


The type of status would be ServiceError, but you are using it as if it was Status.... does this code compile?

add readme file

da8a2dd

coryan requested changes Mar 8, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add readme file #1387

add readme file #1387

hghalebi commented Feb 27, 2025

google-cla bot commented Feb 27, 2025

coryan commented Feb 27, 2025

hghalebi commented Feb 28, 2025

hghalebi commented Feb 28, 2025

coryan commented Feb 28, 2025

hghalebi commented Mar 5, 2025

coryan commented Mar 5, 2025

hghalebi commented Mar 6, 2025

hghalebi commented Mar 8, 2025

coryan commented Mar 8, 2025

codecov bot commented Mar 8, 2025

coryan Mar 8, 2025

coryan Mar 8, 2025

coryan Mar 8, 2025

coryan Mar 8, 2025

coryan Mar 8, 2025

coryan Mar 8, 2025

coryan Mar 8, 2025

coryan Mar 8, 2025

add readme file #1387

Are you sure you want to change the base?

add readme file #1387

Conversation

hghalebi commented Feb 27, 2025

Pull Request: Refactor Tutorial to Google Cloud Style Documentation

Description

Changes Made

Key Features

Testing Done

Screenshots

Related Issues

Checklist

Notes for Reviewers

google-cla bot commented Feb 27, 2025

coryan commented Feb 27, 2025

hghalebi commented Feb 28, 2025

hghalebi commented Feb 28, 2025

coryan commented Feb 28, 2025

hghalebi commented Mar 5, 2025

coryan commented Mar 5, 2025

hghalebi commented Mar 6, 2025

hghalebi commented Mar 8, 2025

coryan commented Mar 8, 2025

codecov bot commented Mar 8, 2025

Codecov Report

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