Skip to content

Commit ccd1c33

Browse files
leemthompoleemthompo
authored
[DOCS] Update hardcoded reference doc links URLs for v9 (#124798)
1 parent b1e878f commit ccd1c33

File tree

13 files changed

+154
-131
lines changed

13 files changed

+154
-131
lines changed

‎server/src/main/java/org/elasticsearch/common/ReferenceDocs.java‎

Lines changed: 30 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@
1111

1212
import org.elasticsearch.Build;
1313
import org.elasticsearch.core.SuppressForbidden;
14-
import org.elasticsearch.core.UpdateForV9;
1514

1615
import java.io.BufferedReader;
1716
import java.io.FileNotFoundException;
@@ -28,7 +27,6 @@
2827
* {@link #toString()} yields (a string representation of) a URL for the relevant docs. Links are defined in the resource file
2928
* {@code reference-docs-links.txt} which must include definitions for exactly the set of values of this enum.
3029
*/
31-
@UpdateForV9(owner = UpdateForV9.Owner.DOCS) // the docs are completely different in v9 so these links all need fixing
3230
public enum ReferenceDocs {
3331
/*
3432
* Note that the docs subsystem parses {@code reference-docs-links.txt} differently. See {@code sub check_elasticsearch_links} in
@@ -89,7 +87,22 @@ public enum ReferenceDocs {
8987
// this comment keeps the ';' on the next line so every entry above has a trailing ',' which makes the diff for adding new links cleaner
9088
;
9189

92-
private static final Map<String, String> linksBySymbol;
90+
private static final Map<String, LinkComponents> linksBySymbol;
91+
92+
record LinkComponents(String path, String fragment) {
93+
static LinkComponents ofLink(String link) {
94+
if (link.indexOf('?') != -1) {
95+
throw new IllegalStateException("ReferenceDocs does not support links containing pre-existing query parameters: " + link);
96+
}
97+
98+
final var fragmentIndex = link.indexOf('#');
99+
if (fragmentIndex == -1) {
100+
return new LinkComponents(link, "");
101+
} else {
102+
return new LinkComponents(link.substring(0, fragmentIndex), link.substring(fragmentIndex));
103+
}
104+
}
105+
}
93106

94107
static {
95108
try (var resourceStream = readFromJarResourceUrl(ReferenceDocs.class.getResource("reference-docs-links.txt"))) {
@@ -106,30 +119,17 @@ public enum ReferenceDocs {
106119

107120
static final int SYMBOL_COLUMN_WIDTH = 64; // increase as needed to accommodate yet longer symbols
108121

109-
static Map<String, String> readLinksBySymbol(InputStream inputStream) throws IOException {
110-
final var padding = " ".repeat(SYMBOL_COLUMN_WIDTH);
111-
112-
record LinksBySymbolEntry(String symbol, String link) implements Map.Entry<String, String> {
113-
@Override
114-
public String getKey() {
115-
return symbol;
116-
}
117-
118-
@Override
119-
public String getValue() {
120-
return link;
121-
}
122-
123-
@Override
124-
public String setValue(String value) {
125-
assert false;
126-
throw new UnsupportedOperationException();
127-
}
128-
}
129-
130-
final var symbolCount = values().length;
131-
final var linksBySymbolEntries = new LinksBySymbolEntry[symbolCount];
122+
// exposed for tests
123+
@SuppressWarnings({ "unchecked", "rawtypes" })
124+
static Map<String, LinkComponents> readLinksBySymbol(InputStream inputStream) throws IOException {
125+
final var linksBySymbolEntries = new Map.Entry[values().length];
126+
createLinkComponentEntries(inputStream, linksBySymbolEntries);
127+
return Map.ofEntries(linksBySymbolEntries);
128+
}
132129

130+
private static void createLinkComponentEntries(InputStream inputStream, Map.Entry<?, ?>[] linksBySymbolEntries) throws IOException {
131+
final var padding = " ".repeat(SYMBOL_COLUMN_WIDTH);
132+
final var symbolCount = linksBySymbolEntries.length;
133133
try (var reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
134134
for (int i = 0; i < symbolCount; i++) {
135135
final var currentLine = reader.readLine();
@@ -158,15 +158,13 @@ public String setValue(String value) {
158158
"found auto-generated fragment ID in link [" + link + "] for [" + symbol + "] at line " + (i + 1)
159159
);
160160
}
161-
linksBySymbolEntries[i] = new LinksBySymbolEntry(symbol, link);
161+
linksBySymbolEntries[i] = Map.entry(symbol, LinkComponents.ofLink(link));
162162
}
163163

164164
if (reader.readLine() != null) {
165165
throw new IllegalStateException("unexpected trailing content at line " + (symbolCount + 1));
166166
}
167167
}
168-
169-
return Map.ofEntries(linksBySymbolEntries);
170168
}
171169

172170
/**
@@ -196,13 +194,14 @@ static String getVersionComponent(String version, boolean isSnapshot) {
196194
return UNRELEASED_VERSION_COMPONENT;
197195
}
198196
// Non-semantic, released version -> point to latest information (current release documentation, e.g.
199-
// https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-plugins.html)
197+
// https://www.elastic.co/docs/modules-plugins?version=current)
200198
return CURRENT_VERSION_COMPONENT;
201199
}
202200

203201
@Override
204202
public String toString() {
205-
return "https://www.elastic.co/guide/en/elasticsearch/reference/" + VERSION_COMPONENT + "/" + linksBySymbol.get(name());
203+
final var linkComponents = linksBySymbol.get(name());
204+
return "https://www.elastic.co/docs/" + linkComponents.path() + "?version=" + VERSION_COMPONENT + linkComponents.fragment();
206205
}
207206

208207
@SuppressForbidden(reason = "reads resource from jar")

‎server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt‎

Lines changed: 48 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,48 @@
1-
INITIAL_MASTER_NODES important-settings.html#initial_master_nodes
2-
DISCOVERY_TROUBLESHOOTING discovery-troubleshooting.html
3-
UNSTABLE_CLUSTER_TROUBLESHOOTING troubleshooting-unstable-cluster.html
4-
LAGGING_NODE_TROUBLESHOOTING troubleshooting-unstable-cluster.html#troubleshooting-unstable-cluster-lagging
5-
SHARD_LOCK_TROUBLESHOOTING troubleshooting-unstable-cluster.html#troubleshooting-unstable-cluster-shardlockobtainfailedexception
6-
NETWORK_DISCONNECT_TROUBLESHOOTING troubleshooting-unstable-cluster.html#troubleshooting-unstable-cluster-network
7-
CONCURRENT_REPOSITORY_WRITERS diagnosing-corrupted-repositories.html
8-
ARCHIVE_INDICES archive-indices.html
9-
HTTP_TRACER modules-network.html#http-rest-request-tracer
10-
LOGGING logging.html
11-
BOOTSTRAP_CHECK_HEAP_SIZE bootstrap-checks-heap-size.html
12-
BOOTSTRAP_CHECK_FILE_DESCRIPTOR bootstrap-checks-file-descriptor.html
13-
BOOTSTRAP_CHECK_MEMORY_LOCK bootstrap-checks-memory-lock.html
14-
BOOTSTRAP_CHECK_MAX_NUMBER_THREADS max-number-threads-check.html
15-
BOOTSTRAP_CHECK_MAX_FILE_SIZE bootstrap-checks-max-file-size.html
16-
BOOTSTRAP_CHECK_MAX_SIZE_VIRTUAL_MEMORY max-size-virtual-memory-check.html
17-
BOOTSTRAP_CHECK_MAXIMUM_MAP_COUNT bootstrap-checks-max-map-count.html
18-
BOOTSTRAP_CHECK_CLIENT_JVM bootstrap-checks-client-jvm.html
19-
BOOTSTRAP_CHECK_USE_SERIAL_COLLECTOR bootstrap-checks-serial-collector.html
20-
BOOTSTRAP_CHECK_SYSTEM_CALL_FILTER bootstrap-checks-syscall-filter.html
21-
BOOTSTRAP_CHECK_ONERROR_AND_ONOUTOFMEMORYERROR bootstrap-checks-onerror.html
22-
BOOTSTRAP_CHECK_EARLY_ACCESS bootstrap-checks-early-access.html
23-
BOOTSTRAP_CHECK_ALL_PERMISSION bootstrap-checks-all-permission.html
24-
BOOTSTRAP_CHECK_DISCOVERY_CONFIGURATION bootstrap-checks-discovery-configuration.html
25-
BOOTSTRAP_CHECKS bootstrap-checks.html
26-
BOOTSTRAP_CHECK_ENCRYPT_SENSITIVE_DATA bootstrap-checks-xpack.html#bootstrap-checks-xpack-encrypt-sensitive-data
27-
BOOTSTRAP_CHECK_PKI_REALM bootstrap-checks-xpack.html#bootstrap-checks-xpack-pki-realm
28-
BOOTSTRAP_CHECK_ROLE_MAPPINGS bootstrap-checks-xpack.html#bootstrap-checks-xpack-role-mappings
29-
BOOTSTRAP_CHECK_TLS bootstrap-checks-xpack.html#bootstrap-checks-tls
30-
BOOTSTRAP_CHECK_TOKEN_SSL bootstrap-checks-xpack.html#bootstrap-checks-xpack-token-ssl
31-
CONTACT_SUPPORT troubleshooting.html#troubleshooting-contact-support
32-
UNASSIGNED_SHARDS red-yellow-cluster-status.html
33-
EXECUTABLE_JNA_TMPDIR executable-jna-tmpdir.html
34-
NETWORK_THREADING_MODEL modules-network.html#modules-network-threading-model
35-
ALLOCATION_EXPLAIN_API cluster-allocation-explain.html
36-
NETWORK_BINDING_AND_PUBLISHING modules-network.html#modules-network-binding-publishing
37-
SNAPSHOT_REPOSITORY_ANALYSIS repo-analysis-api.html
38-
S3_COMPATIBLE_REPOSITORIES repository-s3.html#repository-s3-compatible-services
39-
LUCENE_MAX_DOCS_LIMIT size-your-shards.html#troubleshooting-max-docs-limit
40-
MAX_SHARDS_PER_NODE size-your-shards.html#troubleshooting-max-shards-open
41-
FLOOD_STAGE_WATERMARK fix-watermark-errors.html
42-
X_OPAQUE_ID api-conventions.html#x-opaque-id
43-
FORMING_SINGLE_NODE_CLUSTERS modules-discovery-bootstrap-cluster.html#modules-discovery-bootstrap-cluster-joining
44-
CIRCUIT_BREAKER_ERRORS circuit-breaker-errors.html
45-
ALLOCATION_EXPLAIN_NO_COPIES cluster-allocation-explain.html#no-valid-shard-copy
46-
ALLOCATION_EXPLAIN_MAX_RETRY cluster-allocation-explain.html#maximum-number-of-retries-exceeded
47-
SECURE_SETTINGS secure-settings.html
48-
CLUSTER_SHARD_LIMIT misc-cluster-settings.html#cluster-shard-limit
1+
INITIAL_MASTER_NODES deploy-manage/deploy/self-managed/important-settings-configuration#initial_master_nodes
2+
DISCOVERY_TROUBLESHOOTING troubleshoot/elasticsearch/discovery-troubleshooting
3+
UNSTABLE_CLUSTER_TROUBLESHOOTING troubleshoot/elasticsearch/troubleshooting-unstable-cluster
4+
LAGGING_NODE_TROUBLESHOOTING troubleshoot/elasticsearch/troubleshooting-unstable-cluster#troubleshooting-unstable-cluster-lagging
5+
SHARD_LOCK_TROUBLESHOOTING troubleshoot/elasticsearch/troubleshooting-unstable-cluster#troubleshooting-unstable-cluster-shardlockobtainfailedexception
6+
NETWORK_DISCONNECT_TROUBLESHOOTING troubleshoot/elasticsearch/troubleshooting-unstable-cluster#troubleshooting-unstable-cluster-network
7+
CONCURRENT_REPOSITORY_WRITERS troubleshoot/elasticsearch/diagnosing-corrupted-repositories
8+
ARCHIVE_INDICES deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions
9+
HTTP_TRACER reference/elasticsearch/configuration-reference/networking-settings#http-rest-request-tracer
10+
LOGGING deploy-manage/monitor/logging-configuration/elasticsearch-deprecation-logs
11+
BOOTSTRAP_CHECK_HEAP_SIZE deploy-manage/deploy/self-managed/bootstrap-checks#heap-size
12+
BOOTSTRAP_CHECK_FILE_DESCRIPTOR deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-file-descriptor
13+
BOOTSTRAP_CHECK_MEMORY_LOCK deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-memory-lock
14+
BOOTSTRAP_CHECK_MAX_NUMBER_THREADS deploy-manage/deploy/self-managed/bootstrap-checks#max-number-threads-check
15+
BOOTSTRAP_CHECK_MAX_FILE_SIZE deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-max-file-size
16+
BOOTSTRAP_CHECK_MAX_SIZE_VIRTUAL_MEMORY deploy-manage/deploy/self-managed/bootstrap-checks#max-size-virtual-memory-check
17+
BOOTSTRAP_CHECK_MAXIMUM_MAP_COUNT deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-max-map-count
18+
BOOTSTRAP_CHECK_CLIENT_JVM deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-client-jvm
19+
BOOTSTRAP_CHECK_USE_SERIAL_COLLECTOR deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-serial-collector
20+
BOOTSTRAP_CHECK_SYSTEM_CALL_FILTER deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-syscall-filter
21+
BOOTSTRAP_CHECK_ONERROR_AND_ONOUTOFMEMORYERROR deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-onerror
22+
BOOTSTRAP_CHECK_EARLY_ACCESS deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-early-access
23+
BOOTSTRAP_CHECK_ALL_PERMISSION deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-all-permission
24+
BOOTSTRAP_CHECK_DISCOVERY_CONFIGURATION deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-discovery-configuration
25+
BOOTSTRAP_CHECKS deploy-manage/deploy/self-managed/bootstrap-checks
26+
BOOTSTRAP_CHECK_ENCRYPT_SENSITIVE_DATA deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-xpack-encrypt-sensitive-data
27+
BOOTSTRAP_CHECK_PKI_REALM deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-xpack-pki-realm
28+
BOOTSTRAP_CHECK_ROLE_MAPPINGS deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-xpack-role-mappings
29+
BOOTSTRAP_CHECK_TLS deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-tls
30+
BOOTSTRAP_CHECK_TOKEN_SSL deploy-manage/deploy/self-managed/bootstrap-checks#bootstrap-checks-xpack-token-ssl
31+
CONTACT_SUPPORT troubleshoot#contact-us
32+
UNASSIGNED_SHARDS troubleshoot/elasticsearch/red-yellow-cluster-status
33+
EXECUTABLE_JNA_TMPDIR deploy-manage/deploy/self-managed/executable-jna-tmpdir
34+
NETWORK_THREADING_MODEL reference/elasticsearch/configuration-reference/networking-settings#modules-network-threading-model
35+
ALLOCATION_EXPLAIN_API api/doc/elasticsearch/v9/operation/operation-cluster-allocation-explain
36+
NETWORK_BINDING_AND_PUBLISHING reference/elasticsearch/configuration-reference/networking-settings#modules-network-binding-publishing
37+
SNAPSHOT_REPOSITORY_ANALYSIS api/doc/elasticsearch/v9/operation/operation-snapshot-repository-analyze
38+
S3_COMPATIBLE_REPOSITORIES deploy-manage/tools/snapshot-and-restore/s3-repository#repository-s3-compatible-services
39+
LUCENE_MAX_DOCS_LIMIT deploy-manage/production-guidance/optimize-performance/size-shards#troubleshooting-max-docs-limit
40+
MAX_SHARDS_PER_NODE deploy-manage/production-guidance/optimize-performance/size-shards#troubleshooting-max-shards-open
41+
FLOOD_STAGE_WATERMARK troubleshoot/elasticsearch/fix-watermark-errors
42+
X_OPAQUE_ID reference/elasticsearch/rest-apis/api-conventions#x-opaque-id
43+
FORMING_SINGLE_NODE_CLUSTERS deploy-manage/distributed-architecture/discovery-cluster-formation/modules-discovery-bootstrap-cluster#modules-discovery-bootstrap-cluster-joining
44+
CIRCUIT_BREAKER_ERRORS troubleshoot/elasticsearch/circuit-breaker-errors
45+
ALLOCATION_EXPLAIN_NO_COPIES troubleshoot/elasticsearch/diagnose-unassigned-shards#no-shard-copy
46+
ALLOCATION_EXPLAIN_MAX_RETRY troubleshoot/elasticsearch/diagnose-unassigned-shards#maximum-retries-exceeded
47+
SECURE_SETTINGS deploy-manage/security/secure-settings
48+
CLUSTER_SHARD_LIMIT reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings#cluster-shard-limit

‎server/src/test/java/org/elasticsearch/action/admin/cluster/allocation/ClusterAllocationExplainActionTests.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -198,8 +198,7 @@ public void testFindAnyUnassignedShardToExplain() {
198198
// no point in asserting the precise wording of the message into this test, but we care that it contains these bits:
199199
containsString("No shard was specified in the request"),
200200
containsString("specify the target shard in the request"),
201-
containsString("https://www.elastic.co/guide/en/elasticsearch/reference"),
202-
containsString("cluster-allocation-explain.html")
201+
containsString("https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-cluster-allocation-explain")
203202
)
204203
);
205204
}

‎server/src/test/java/org/elasticsearch/action/admin/cluster/allocation/ClusterAllocationExplanationTests.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -151,8 +151,7 @@ public void testRandomShardExplanationToXContent() throws Exception {
151151
// no point in asserting the precise wording of the message into this test, but we care that the note contains these bits:
152152
containsString("No shard was specified in the explain API request"),
153153
containsString("specify the target shard in the request"),
154-
containsString("https://www.elastic.co/guide/en/elasticsearch/reference"),
155-
containsString("cluster-allocation-explain.html")
154+
containsString("https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-cluster-allocation-explain?")
156155
)
157156
);
158157

0 commit comments

Comments
 (0)