docs(compute/v1): initial user guide

Author: coryan

guide/samples/src/compute.rs

@@ -25,6 +25,7 @@ pub mod compute_instances_list_all;
 pub mod compute_instances_operation_check;
 pub mod compute_usage_report_get;
 pub mod compute_usage_report_set;
+pub mod quickstart;
 
 pub async fn cleanup_stale_instances(client: &Instances, project_id: &str) -> anyhow::Result<()> {
     use google_cloud_wkt::Timestamp;

guide/samples/src/compute/compute_instances_create.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// [START compute_instances_create]
+// [START compute_instances_create] ANCHOR: all
 use google_cloud_compute_v1::client::Instances;
 use google_cloud_compute_v1::model::{
     AttachedDisk, AttachedDiskInitializeParams, Instance, NetworkInterface,
@@ -49,4 +49,4 @@ pub async fn sample(client: &Instances, project_id: &str, name: &str) -> anyhow:
 
     Ok(())
 }
-// [END compute_instances_create]
+// [END compute_instances_create] ANCHOR_END: all

guide/samples/src/compute/compute_instances_delete.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// [START compute_instances_delete]
+// [START compute_instances_delete] ANCHOR: all
 use google_cloud_compute_v1::client::Instances;
 use google_cloud_lro::Poller;
 
@@ -32,4 +32,4 @@ pub async fn sample(client: &Instances, project_id: &str, name: &str) -> anyhow:
 
     Ok(())
 }
-// [END compute_instances_delete]
+// [END compute_instances_delete] ANCHOR_END: all

guide/samples/src/compute/quickstart.rs

@@ -0,0 +1,22 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+pub async fn quickstart() -> anyhow::Result<()> {
+    // [START rust_compute_instances_client] ANCHOR: client
+    use google_cloud_compute_v1::client::Instances;
+    let client = Instances::builder().build().await?;
+    // [END rust_compute_instances_client] ANCHOR_END: client
+    let _ = client;
+    Ok(())
+}

guide/src/SUMMARY.md

@@ -1,4 +1,4 @@
-<!-- 
+<!--
 Copyright 2025 Google LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
@@ -27,6 +27,7 @@ limitations under the License.
   - [Speed up large object downloads](storage/striped_downloads.md)
   - [Use errors to terminate uploads](storage/terminate_uploads.md)
   - [How to write tests using the Storage client](storage/mocking.md)
+- [Using the Compute Engine API](compute.md)
 - [Update a resource using a field mask](update_resource.md)
 - [Configuring retry policies](configuring_retry_policies.md)
 - [Error handling](error_handling.md)

guide/src/compute.md

@@ -0,0 +1,73 @@
+<!--
+Copyright 2025 Google LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Using the Compute Engine API
+
+The [Compute Engine] API allows you to create and run virtual machines (VMs) on
+Google Cloud.
+
+This guide shows you how to initialize the Compute Engine client library for
+Rust, and how to perform some basic operations using the library.
+
+## Pre-requisites
+
+The guide assumes you have an existing [Google Cloud project] with
+[billing enabled].
+
+## Add the client library as a dependency
+
+Use `cargo` to add the necessary dependency:
+
+```toml
+cargo add google-cloud-compute-v1
+```
+
+## Create a virtual machine
+
+The client to create, and manipulate virtual machines is called `Instances`:
+
+```rust,ignore,noplayground
+{{#rustdoc_include ../samples/src/compute/quickstart.rs:client}}
+```
+
+The client has several methods. For example `insert()` creates a new virtual
+machine:
+
+```rust,ignore,noplayground
+{{#rustdoc_include ../samples/src/compute/compute_instances_create.rs:all}}
+```
+
+Note that this is a [long-running operation], you need to wait for its outcome,
+and verify if there are any errors.
+
+## Cleanup
+
+Delete the virtual machine using the console, or the `delete()` method:
+
+```rust,ignore,noplayground
+{{#rustdoc_include ../samples/src/compute/compute_instances_delete.rs:all}}
+```
+
+## Next Steps
+
+- [Working with long-running operations](/working_with_long_running_operations.md)
+- [Configuring polling policies](/configuring_polling_policies.md)
+- [Compute Engine client libraries](https://cloud.google.com/compute/docs/api/libraries)
+
+[billing enabled]: https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project
+[compute engine]: https://cloud.google.com/compute
+[google cloud project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects
+[long-running operation]: /working_with_long_running_operations.md