Skip to content

Commit 1d1ad99

Browse files
coryancoryan
authored
doc: split environment variables from landing page (#11381)
The landing pages for the reference docs are too cluttered. This does not fix all the problems, but it is a good start.
1 parent 9a18f09 commit 1d1ad99

209 files changed

Lines changed: 5607 additions & 3380 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎ci/generate-markdown/split-env-from-main-dox.sh‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
#!/bin/bash
2+
#
3+
# Copyright 2023 Google LLC
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -euo pipefail
18+
19+
mapfile -t ga_list < <(cmake -DCMAKE_MODULE_PATH="${PWD}/cmake" -P cmake/print-ga-libraries.cmake 2>&1)
20+
21+
for library in "${ga_list[@]}"; do
22+
maindox="google/cloud/${library}/doc/main.dox"
23+
envdox="google/cloud/${library}/doc/environment-variables.dox"
24+
if [[ ! -r "${maindox}" ]]; then
25+
echo "Skip ${library}, no main.dox"
26+
continue
27+
fi
28+
if ! grep -q '^## Environment Variables' "${maindox}"; then
29+
echo "Skip ${library}, no Environment Variables section in main.dox"
30+
continue
31+
fi
32+
echo "Processing ${library}"
33+
(
34+
cat <<_EOF_
35+
/*!
36+
37+
@page ${library}-env Environment Variables
38+
39+
A number of environment variables can be used to configure the behavior of
40+
the library. There are also functions to configure this behavior in code. The
41+
environment variables are convenient when troubleshooting problems.
42+
43+
@section ${library}-env-endpoint Endpoint Overrides
44+
45+
_EOF_
46+
sed -e '1,/^## Environment Variables/d' \
47+
-e '/^<!-- inject-endpoint-env-vars-end -->/,$d' \
48+
"${maindox}"
49+
sed "s/@library@/${library}/" <<'_EOF_'
50+
<!-- inject-endpoint-env-vars-end -->
51+
52+
@section @library@-logging Logging
53+
54+
`GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc`: turns on tracing for most gRPC
55+
calls. The library injects an additional Stub decorator that prints each gRPC
56+
request and response. Unless you have configured you own logging backend,
57+
you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
58+
the program's console.
59+
60+
@see google::cloud::TracingComponentsOption
61+
62+
`GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...\`: modifies the behavior of gRPC tracing,
63+
including whether messages will be output on multiple lines, or whether
64+
string/bytes fields will be truncated.
65+
66+
@see google::cloud::TracingOptionsOption
67+
68+
`GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes`: turns on logging in the library, basically
69+
the library always "logs" but the logging infrastructure has no backend to
70+
actually print anything until the application sets a backend or they set this
71+
environment variable.
72+
73+
@see google::cloud::LogBackend
74+
@see google::cloud::LogSink
75+
76+
@section @library@-env-project Setting the Default Project
77+
78+
`GOOGLE_CLOUD_PROJECT=...`: is used in examples and integration tests to
79+
configure the GCP project. This has no effect in the library.
80+
81+
*/
82+
_EOF_
83+
) >"${envdox}"
84+
sed -n '1,/^## Environment Variables/p;/^## Error Handling/,$p' "${maindox}" |
85+
sed -e '/^## Environment Variables/d' |
86+
sponge "${maindox}"
87+
done

‎ci/generate-markdown/update-library-landing-dox.sh‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ readonly LIBRARY=$1
2929

3030
readonly LIB="google/cloud/${LIBRARY}"
3131
readonly MAIN_DOX="google/cloud/${LIBRARY}/doc/main.dox"
32+
readonly ENVIRONMENT_DOX="google/cloud/${LIBRARY}/doc/environment-variables.dox"
3233
if [[ ! -r "${MAIN_DOX}" ]]; then
3334
exit 0
3435
fi
@@ -57,7 +58,7 @@ while IFS= read -r -d $'\0' option_defaults_cc; do
5758
env_vars[$(printf '%s\\\n' "${env_var[@]}")]=""
5859
done < <(git ls-files -z -- "${LIB}/*_option_defaults.cc")
5960
mapfile -d '' sorted_env_vars < <(printf '%s\0' "${!env_vars[@]}" | sort -z)
60-
sed -i -f - "${MAIN_DOX}" <<EOT
61+
sed -i -f - "${ENVIRONMENT_DOX}" <<EOT
6162
/${inject_start}/,/${inject_end}/c \\
6263
${inject_start}\\
6364
$(printf '%s\n' "${sorted_env_vars[@]}")

‎generator/internal/scaffold_generator.cc‎

Lines changed: 53 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,7 @@ void GenerateScaffold(
165165
{"BUILD.bazel", GenerateBuild},
166166
{"CMakeLists.txt", GenerateCMakeLists},
167167
{"doc/main.dox", GenerateDoxygenMainPage},
168+
{"doc/environment-variables.dox", GenerateDoxygenEnvironmentPage},
168169
{"doc/options.dox", GenerateDoxygenOptionsPage},
169170
{"quickstart/README.md", GenerateQuickstartReadme},
170171
{"quickstart/quickstart.cc", GenerateQuickstartSkeleton},
@@ -582,29 +583,6 @@ which should give you a taste of the $title$ C++ client library API.
582583
583584
@snippet quickstart.cc all
584585
585-
## Environment Variables
586-
587-
<!-- inject-endpoint-env-vars-start -->
588-
<!-- inject-endpoint-env-vars-end -->
589-
590-
- `GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc` turns on tracing for most gRPC
591-
calls. The library injects an additional Stub decorator that prints each gRPC
592-
request and response. Unless you have configured your own logging backend,
593-
you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
594-
the program's console.
595-
596-
- `GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc-streams` turns on tracing for streaming
597-
gRPC calls. This can produce a lot of output, so use with caution!
598-
599-
- `GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...` modifies the behavior of gRPC tracing,
600-
including whether messages will be output on multiple lines, or whether
601-
string/bytes fields will be truncated.
602-
603-
- `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` turns on logging in the library. Basically
604-
the library always "logs" but the logging infrastructure has no backend to
605-
actually print anything until the application sets a backend or it sets this
606-
environment variable.
607-
608586
## Error Handling
609587
610588
[status-or-header]: https://github.com/googleapis/google-cloud-cpp/blob/main/google/cloud/status_or.h
@@ -676,6 +654,58 @@ can override the default policies.
676654
printer.Print(variables, kText);
677655
}
678656

657+
void GenerateDoxygenEnvironmentPage(
658+
std::ostream& os, std::map<std::string, std::string> const& variables) {
659+
auto constexpr kText = R"""(/*!
660+
661+
@page $library$-env Environment Variables
662+
663+
A number of environment variables can be used to configure the behavior of
664+
the library. There are also functions to configure this behavior in code. The
665+
environment variables are convenient when troubleshooting problems.
666+
667+
@section $library$-env-endpoint Endpoint Overrides
668+
<!-- inject-endpoint-env-vars-start -->
669+
<!-- inject-endpoint-env-vars-end -->
670+
671+
@see google::cloud::EndpointOption
672+
673+
@section $library$-env-logging Logging
674+
675+
`GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc`: turns on tracing for most gRPC
676+
calls. The library injects an additional Stub decorator that prints each gRPC
677+
request and response. Unless you have configured your own logging backend,
678+
you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
679+
the program's console.
680+
681+
@see google::cloud::TracingComponentsOption
682+
683+
`GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...`: modifies the behavior of gRPC tracing,
684+
including whether messages will be output on multiple lines, or whether
685+
string/bytes fields will be truncated.
686+
687+
@see google::cloud::TracingOptionsOption
688+
689+
`GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes`: turns on logging in the library, basically
690+
the library always "logs" but the logging infrastructure has no backend to
691+
actually print anything until the application sets a backend or they set this
692+
environment variable.
693+
694+
@see google::cloud::LogBackend
695+
@see google::cloud::LogSink
696+
697+
@section $library$-env-project Setting the Default Project
698+
699+
`GOOGLE_CLOUD_PROJECT=...`: is used in examples and integration tests to
700+
configure the GCP project. This has no effect in the library.
701+
702+
*/
703+
)""";
704+
google::protobuf::io::OstreamOutputStream output(&os);
705+
google::protobuf::io::Printer printer(&output, '$');
706+
printer.Print(variables, kText);
707+
}
708+
679709
void GenerateDoxygenOptionsPage(
680710
std::ostream& os, std::map<std::string, std::string> const& variables) {
681711
auto constexpr kText = R"""(/*!

‎generator/internal/scaffold_generator.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,8 @@ void GenerateDoxygenMainPage(
8585
std::ostream& os, std::map<std::string, std::string> const& variables);
8686
void GenerateDoxygenOptionsPage(
8787
std::ostream& os, std::map<std::string, std::string> const& variables);
88+
void GenerateDoxygenEnvironmentPage(
89+
std::ostream& os, std::map<std::string, std::string> const& variables);
8890
void GenerateQuickstartReadme(
8991
std::ostream& os, std::map<std::string, std::string> const& variables);
9092
void GenerateQuickstartSkeleton(

‎generator/internal/scaffold_generator_test.cc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,25 @@ TEST_F(ScaffoldGenerator, DoxygenOptionsPage) {
286286
)"""));
287287
}
288288

289+
TEST_F(ScaffoldGenerator, DoxygenEnvironmentPage) {
290+
auto const vars = ScaffoldVars(path(), service(), false);
291+
std::ostringstream os;
292+
GenerateDoxygenEnvironmentPage(os, vars);
293+
auto const actual = std::move(os).str();
294+
EXPECT_THAT(actual, AllOf(HasSubstr(R"""(
295+
@page test-env Environment Variables
296+
)"""),
297+
HasSubstr(R"""(
298+
@section test-env-logging Logging
299+
)"""),
300+
HasSubstr(R"""(
301+
@section test-env-endpoint Endpoint Overrides
302+
)"""),
303+
HasSubstr(R"""(
304+
@section test-env-project Setting the Default Project
305+
)""")));
306+
}
307+
289308
TEST_F(ScaffoldGenerator, QuickstartReadme) {
290309
auto const vars = ScaffoldVars(path(), service(), false);
291310
std::ostringstream os;

‎google/cloud/accessapproval/doc/environment-variables.dox‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
/*!
2+
3+
@page accessapproval-env Environment Variables
4+
5+
A number of environment variables can be used to configure the behavior of
6+
the library. There are also functions to configure this behavior in code. The
7+
environment variables are convenient when troubleshooting problems.
8+
9+
@section accessapproval-env-endpoint Endpoint Overrides
10+
11+
12+
<!-- inject-endpoint-env-vars-start -->
13+
14+
- `GOOGLE_CLOUD_CPP_ACCESS_APPROVAL_ENDPOINT=...` overrides the
15+
`EndpointOption` (which defaults to "accessapproval.googleapis.com")
16+
used by `MakeAccessApprovalConnection()`.
17+
18+
<!-- inject-endpoint-env-vars-end -->
19+
20+
@section accessapproval-logging Logging
21+
22+
`GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc`: turns on tracing for most gRPC
23+
calls. The library injects an additional Stub decorator that prints each gRPC
24+
request and response. Unless you have configured your own logging backend,
25+
you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
26+
the program's console.
27+
28+
@see google::cloud::TracingComponentsOption
29+
30+
`GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...`: modifies the behavior of gRPC tracing,
31+
including whether messages will be output on multiple lines, or whether
32+
string/bytes fields will be truncated.
33+
34+
@see google::cloud::TracingOptionsOption
35+
36+
`GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes`: turns on logging in the library, basically
37+
the library always "logs" but the logging infrastructure has no backend to
38+
actually print anything until the application sets a backend or they set this
39+
environment variable.
40+
41+
@see google::cloud::LogBackend
42+
@see google::cloud::LogSink
43+
44+
@section accessapproval-env-project Setting the Default Project
45+
46+
`GOOGLE_CLOUD_PROJECT=...`: is used in examples and integration tests to
47+
configure the GCP project. This has no effect in the library.
48+
49+
*/

‎google/cloud/accessapproval/doc/main.dox‎

Lines changed: 0 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -40,34 +40,6 @@ which should give you a taste of the Access Approval API C++ client library API.
4040

4141
@snippet quickstart.cc all
4242

43-
## Environment Variables
44-
45-
<!-- inject-endpoint-env-vars-start -->
46-
47-
- `GOOGLE_CLOUD_CPP_ACCESS_APPROVAL_ENDPOINT=...` overrides the
48-
`EndpointOption` (which defaults to "accessapproval.googleapis.com")
49-
used by `MakeAccessApprovalConnection()`.
50-
51-
<!-- inject-endpoint-env-vars-end -->
52-
53-
- `GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc` turns on tracing for most gRPC
54-
calls. The library injects an additional Stub decorator that prints each gRPC
55-
request and response. Unless you have configured your own logging backend,
56-
you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
57-
the program's console.
58-
59-
- `GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc-streams` turns on tracing for streaming
60-
gRPC calls. This can produce a lot of output, so use with caution!
61-
62-
- `GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...` modifies the behavior of gRPC tracing,
63-
including whether messages will be output on multiple lines, or whether
64-
string/bytes fields will be truncated.
65-
66-
- `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` turns on logging in the library. Basically
67-
the library always "logs" but the logging infrastructure has no backend to
68-
actually print anything until the application sets a backend or it sets this
69-
environment variable.
70-
7143
## Error Handling
7244

7345
[status-or-header]: https://github.com/googleapis/google-cloud-cpp/blob/main/google/cloud/status_or.h

‎google/cloud/accesscontextmanager/doc/environment-variables.dox‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
/*!
2+
3+
@page accesscontextmanager-env Environment Variables
4+
5+
A number of environment variables can be used to configure the behavior of
6+
the library. There are also functions to configure this behavior in code. The
7+
environment variables are convenient when troubleshooting problems.
8+
9+
@section accesscontextmanager-env-endpoint Endpoint Overrides
10+
11+
12+
<!-- inject-endpoint-env-vars-start -->
13+
14+
- `GOOGLE_CLOUD_CPP_ACCESS_CONTEXT_MANAGER_ENDPOINT=...` overrides the
15+
`EndpointOption` (which defaults to "accesscontextmanager.googleapis.com")
16+
used by `MakeAccessContextManagerConnection()`.
17+
18+
<!-- inject-endpoint-env-vars-end -->
19+
20+
@section accesscontextmanager-logging Logging
21+
22+
`GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc`: turns on tracing for most gRPC
23+
calls. The library injects an additional Stub decorator that prints each gRPC
24+
request and response. Unless you have configured your own logging backend,
25+
you should also set `GOOGLE_CLOUD_CPP_ENABLE_CLOG` to produce any output on
26+
the program's console.
27+
28+
@see google::cloud::TracingComponentsOption
29+
30+
`GOOGLE_CLOUD_CPP_TRACING_OPTIONS=...`: modifies the behavior of gRPC tracing,
31+
including whether messages will be output on multiple lines, or whether
32+
string/bytes fields will be truncated.
33+
34+
@see google::cloud::TracingOptionsOption
35+
36+
`GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes`: turns on logging in the library, basically
37+
the library always "logs" but the logging infrastructure has no backend to
38+
actually print anything until the application sets a backend or they set this
39+
environment variable.
40+
41+
@see google::cloud::LogBackend
42+
@see google::cloud::LogSink
43+
44+
@section accesscontextmanager-env-project Setting the Default Project
45+
46+
`GOOGLE_CLOUD_PROJECT=...`: is used in examples and integration tests to
47+
configure the GCP project. This has no effect in the library.
48+
49+
*/

0 commit comments

Comments
 (0)