cleanup: add links to generate lib docs (#12257)

alevenberg · web-flow · commit 10ff712d5435 · 2023-07-31T10:01:02.000-04:00
diff --git a/doc/contributor/howto-guide-adding-generated-libraries.md b/doc/contributor/howto-guide-adding-generated-libraries.md
@@ -5,6 +5,9 @@ This document describes the steps required to add a new library to
 familiar with the existing libraries, the build systems used in those libraries,
 and which libraries are based on gRPC.
 
+- [Adding a new library](#adding-a-new-library)
+- [Expanding a library](#expanding-a-library)
+
 ## Adding a new library
 
 > :warning: For libraries that include multiple services, the scaffold README
@@ -35,12 +38,22 @@ bazel --batch query --noshow_progress --noshow_loading_progress \
     "kind(cc_library, @com_google_googleapis//${subdir}/...)"
 ```
 
-If this fails, send a CL to add the rule. Wait until that is submitted and
-exported before proceeding any further.
+If the command fails, it returns something like this:
+
+```shell
+ERROR: no targets found beneath 'commerce'
+```
+
+This means the dependency does not exist at the pinned version of the googleapis
+repo.
+[Send a PR to update the googleapis SHA to the latest version](../contributor/howto-guide-update-googleapis-sha.md).
+Wait until that is submitted before proceeding any further.
 
 ### Edit the scripts and configuration
 
-Update the `external/googleapis/update_libraries.sh` script.
+Update the
+[external/googleapis/update_libraries.sh](../../external/googleapis/update_libraries.sh)
+script.
 
 <details>
 <summary>Expand for an example</summary>
@@ -71,7 +84,9 @@ index cdaa0bc9f..b0381d72d 100755
 Determine the retryable status codes by looking in the service config JSON. For
 example, [here][retryable-status-codes].
 
-Manually edit `generator/generator_config.textproto` and add the new service.
+Manually edit
+[generator/generator_config.textproto](../../generator/generator_config.textproto)
+and add the new service.
 
 Find the list of `.proto` files that will need to be included:
 
@@ -149,6 +164,12 @@ git add "google/cloud/${library}"
 ci/cloudbuild/build.sh -t checkers-pr
 ```
 
+### Verify the generated changes look right
+
+```shell
+tree google/cloud/$library
+```
+
 ### Commit all the generated files
 
 ```shell
@@ -186,14 +207,16 @@ knows about one such subdirectory. You may need to manually update the
 
 ### Update the root files
 
-Manually edit `cmake/GoogleCloudCppFeatures.cmake` to include the new target. If
-you are generating a GA library, add it to `GOOGLE_CLOUD_CPP_GA_LIBRARIES`.
-Otherwise, if you are generating an experimental library, add it to
-`GOOGLE_CLOUD_CPP_EXPERIMENTAL_LIBRARIES` and note in a comment when the library
-was generated.
+Manually edit
+[cmake/GoogleCloudCppFeatures.cmake](../../cmake/GoogleCloudCppFeatures.cmake)
+to include the new target. If you are generating a GA library, add it to
+`GOOGLE_CLOUD_CPP_GA_LIBRARIES`. Otherwise, if you are generating an
+experimental library, add it to `GOOGLE_CLOUD_CPP_EXPERIMENTAL_LIBRARIES` and
+note in a comment when the library was generated.
 
-Update `libraries.bzl` to include the new library. While this can be done by
-running a cmake-based build, it is fastest to edit the file manually.
+Update [libraries.bzl](../../libraries.bzl) to include the new library. While
+this can be done by running a cmake-based build, it is fastest to edit the file
+manually.
 
 ### Update the quickstart
 
@@ -219,7 +242,7 @@ running while you work on tweaks to the quickstart and documentation.
 ```shell
 env GOOGLE_CLOUD_CPP_CHECK_API=${library} ci/cloudbuild/build.sh -t check-api-pr
 git add ci/abi-dumps
-git commit -m"Add API baseline"
+git commit -m "Add API baseline"
 ```
 
 ### Update the README files
@@ -244,7 +267,8 @@ with older services we need to edit a few places:
 
 ### Edit the top-level CHANGELOG file
 
-Announce the new library in the CHANGELOG for the next release.
+Announce the new library in the [CHANGELOG.md](../CHANGELOG.md) for the next
+release.
 
 ### Fix formatting nits
 
@@ -287,7 +311,7 @@ index c4ce00489..1858b48dc 100755
 ### Commit these changes
 
 ```shell
-git commit -m"Manually update READMEs, quickstart, and top-level stuff" .
+git commit -m "Manually update READMEs, quickstart, and top-level stuff" .
 ```
 
 ## Expanding a library
