From 888e0e28900a470df448c65d7b99d8065fd60251 Mon Sep 17 00:00:00 2001 From: Greg Greenway Date: Fri, 8 May 2020 17:27:55 -0700 Subject: [PATCH] docs: fix links broken in previous doc cleanup. (#11115) The links were broken in 8e8209fa75f87ab53d4c78a466c8f927df930e50 Fixes: #11078 Signed-off-by: Greg Greenway --- DEPRECATED.md | 3 ++- docs/root/intro/deprecated.rst | 6 ++++++ docs/root/intro/intro.rst | 7 +++++++ docs/root/intro/version_history.rst | 6 ++++++ docs/root/version_history/version_history.rst | 2 ++ source/common/common/BUILD | 5 +++++ source/common/common/documentation_url.h | 13 ++++++++++++ source/common/protobuf/BUILD | 1 + source/common/protobuf/utility.cc | 21 ++++++++----------- source/extensions/common/BUILD | 1 + source/extensions/common/utility.h | 14 ++++++------- 11 files changed, 58 insertions(+), 21 deletions(-) create mode 100644 docs/root/intro/deprecated.rst create mode 100644 docs/root/intro/version_history.rst create mode 100644 source/common/common/documentation_url.h diff --git a/DEPRECATED.md b/DEPRECATED.md index 1b2962adcb97..a82576c77ffa 100644 --- a/DEPRECATED.md +++ b/DEPRECATED.md @@ -1,3 +1,4 @@ # DEPRECATED -The [deprecated log](https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated) can be found in the official Envoy developer documentation. +The [deprecated log](https://www.envoyproxy.io/docs/envoy/latest/version_history/version_history) +for each version can be found in the official Envoy developer documentation. diff --git a/docs/root/intro/deprecated.rst b/docs/root/intro/deprecated.rst new file mode 100644 index 000000000000..e630390e94e5 --- /dev/null +++ b/docs/root/intro/deprecated.rst @@ -0,0 +1,6 @@ +Deprecated +========== + +The deprecations for each version have moved :ref:`here `. + +.. This page only exists because previous versions of Envoy link here. diff --git a/docs/root/intro/intro.rst b/docs/root/intro/intro.rst index 055bca727679..cf3404c363ec 100644 --- a/docs/root/intro/intro.rst +++ b/docs/root/intro/intro.rst @@ -10,3 +10,10 @@ Introduction arch_overview/arch_overview deployment_types/deployment_types getting_help + +.. These pages are only here for redirects from log lines from shipping versions of Envoy, so hide them. +.. toctree:: + :hidden: + + version_history + deprecated diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst new file mode 100644 index 000000000000..307b7bb140e8 --- /dev/null +++ b/docs/root/intro/version_history.rst @@ -0,0 +1,6 @@ +Version History +=============== + +The changes for each version have moved :ref:`here `. + +.. This page only exists because previous versions of Envoy link here. diff --git a/docs/root/version_history/version_history.rst b/docs/root/version_history/version_history.rst index b869b08080e0..6451336bffe7 100644 --- a/docs/root/version_history/version_history.rst +++ b/docs/root/version_history/version_history.rst @@ -1,3 +1,5 @@ +.. _version_history: + Version history --------------- diff --git a/source/common/common/BUILD b/source/common/common/BUILD index af25042d18c5..9429aa2e24c6 100644 --- a/source/common/common/BUILD +++ b/source/common/common/BUILD @@ -72,6 +72,11 @@ envoy_cc_library( hdrs = ["compiler_requirements.h"], ) +envoy_cc_library( + name = "documentation_url_lib", + hdrs = ["documentation_url.h"], +) + envoy_cc_library( name = "empty_string", hdrs = ["empty_string.h"], diff --git a/source/common/common/documentation_url.h b/source/common/common/documentation_url.h new file mode 100644 index 000000000000..dc3e0e352209 --- /dev/null +++ b/source/common/common/documentation_url.h @@ -0,0 +1,13 @@ +namespace Envoy { + +// TODO(ggreenway): replace 'latest' with the current version, pulled from the VERSION file at +// the root of the repo. +#define ENVOY_DOC_URL_ROOT "https://www.envoyproxy.io/docs/envoy/latest" + +#define ENVOY_DOC_URL_VERSION_HISTORY ENVOY_DOC_URL_ROOT "/version_history/version_history" + +#define ENVOY_DOC_URL_RUNTIME_OVERRIDE_DEPRECATED \ + ENVOY_DOC_URL_ROOT \ + "/configuration/operations/runtime#using-runtime-overrides-for-deprecated-features" + +} // namespace Envoy diff --git a/source/common/protobuf/BUILD b/source/common/protobuf/BUILD index 9a9aa1f30624..de33b5516828 100644 --- a/source/common/protobuf/BUILD +++ b/source/common/protobuf/BUILD @@ -64,6 +64,7 @@ envoy_cc_library( "//include/envoy/protobuf:message_validator_interface", "//include/envoy/runtime:runtime_interface", "//source/common/common:assert_lib", + "//source/common/common:documentation_url_lib", "//source/common/common:hash_lib", "//source/common/common:utility_lib", "//source/common/config:api_type_oracle_lib", diff --git a/source/common/protobuf/utility.cc b/source/common/protobuf/utility.cc index 684c8e2ffab1..6aba34ea841b 100644 --- a/source/common/protobuf/utility.cc +++ b/source/common/protobuf/utility.cc @@ -8,6 +8,7 @@ #include "envoy/type/v3/percent.pb.h" #include "common/common/assert.h" +#include "common/common/documentation_url.h" #include "common/common/fmt.h" #include "common/config/api_type_oracle.h" #include "common/config/version_converter.h" @@ -198,11 +199,9 @@ void deprecatedFieldHelper(Runtime::Loader* runtime, bool proto_annotated_as_dep if (warn_only) { ENVOY_LOG_MISC(warn, "{}", with_overridden); } else { - const char fatal_error[] = - " If continued use of this field is absolutely necessary, see " - "https://www.envoyproxy.io/docs/envoy/latest/configuration/operations/runtime" - "#using-runtime-overrides-for-deprecated-features for how to apply a temporary and " - "highly discouraged override."; + const char fatal_error[] = " If continued use of this field is absolutely necessary, " + "see " ENVOY_DOC_URL_RUNTIME_OVERRIDE_DEPRECATED " for how " + "to apply a temporary and highly discouraged override."; throw ProtoValidationException(with_overridden + fatal_error, message); } } @@ -408,8 +407,7 @@ void checkForDeprecatedNonRepeatedEnumValue(const Protobuf::Message& message, enum_value_descriptor->name(), " for enum '", field->full_name(), "' from file ", filename, ". This enum value will be removed from Envoy soon", (default_value ? " so a non-default value must now be explicitly set" : ""), - ". Please see https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated " - "for details."); + ". Please see " ENVOY_DOC_URL_VERSION_HISTORY " for details."); deprecatedFieldHelper( runtime, true /*deprecated*/, enum_value_descriptor->options().GetExtension(envoy::annotations::disallowed_by_default_enum), @@ -440,11 +438,10 @@ class UnexpectedFieldProtoVisitor : public ProtobufMessage::ConstProtoVisitor { // If this field is deprecated, warn or throw an error. if (field.options().deprecated()) { - const std::string warning = absl::StrCat( - "Using {}deprecated option '", field.full_name(), "' from file ", filename, - ". This configuration will be removed from " - "Envoy soon. Please see https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated " - "for details."); + const std::string warning = + absl::StrCat("Using {}deprecated option '", field.full_name(), "' from file ", filename, + ". This configuration will be removed from " + "Envoy soon. Please see " ENVOY_DOC_URL_VERSION_HISTORY " for details."); deprecatedFieldHelper(runtime_, true /*deprecated*/, field.options().GetExtension(envoy::annotations::disallowed_by_default), diff --git a/source/extensions/common/BUILD b/source/extensions/common/BUILD index 11077c08c1e5..035e287aa3c9 100644 --- a/source/extensions/common/BUILD +++ b/source/extensions/common/BUILD @@ -13,6 +13,7 @@ envoy_cc_library( hdrs = ["utility.h"], deps = [ "//include/envoy/runtime:runtime_interface", + "//source/common/common:documentation_url_lib", "//source/common/common:minimal_logger_lib", ], ) diff --git a/source/extensions/common/utility.h b/source/extensions/common/utility.h index c50677c898d9..309dca2e2107 100644 --- a/source/extensions/common/utility.h +++ b/source/extensions/common/utility.h @@ -5,6 +5,7 @@ #include "envoy/common/exception.h" #include "envoy/runtime/runtime.h" +#include "common/common/documentation_url.h" #include "common/common/logger.h" namespace Envoy { @@ -103,9 +104,8 @@ class ExtensionNameUtil { return fmt::format( "Using deprecated {}{}extension name '{}' for '{}'. This name will be removed from Envoy " - "soon. Please see " - "https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated for details.", - extension_type, spacing, deprecated_name, canonical_name); + "soon. Please see {} for details.", + extension_type, spacing, deprecated_name, canonical_name, ENVOY_DOC_URL_VERSION_HISTORY); } static std::string fatalMessage(absl::string_view extension_type, @@ -113,11 +113,9 @@ class ExtensionNameUtil { absl::string_view canonical_name) { std::string err = message(extension_type, deprecated_name, canonical_name); - const char fatal_error[] = - " If continued use of this filter name is absolutely necessary, see " - "https://www.envoyproxy.io/docs/envoy/latest/configuration/operations/runtime" - "#using-runtime-overrides-for-deprecated-features for how to apply a temporary and " - "highly discouraged override."; + const char fatal_error[] = " If continued use of this filter name is absolutely necessary, " + "see " ENVOY_DOC_URL_RUNTIME_OVERRIDE_DEPRECATED " for " + "how to apply a temporary and highly discouraged override."; return err + fatal_error; }