Merge branch 'main' into DOC-5042

Author: cmilesb

build/image_report.py

@@ -0,0 +1,63 @@
+"""Image report
+"""
+
+from pylibs.hugotools import ShortcodeIterator
+
+import argparse
+import os
+
+
+def scan_file(path: str) -> int:
+    """Scans a file for all `image` shortcodes.
+
+    Args:
+        path (str): Path to file.
+
+    Returns:
+        (int) Number of shortcodes found.
+    """
+
+    img_list = []
+
+    with open(path, encoding="utf_8") as md_file:
+        text = md_file.read()
+
+        for img, pos_info in ShortcodeIterator(
+            text, lambda t: t.tag == "image"
+        ):
+            img_list.append((img, pos_info))
+
+    if len(img_list) > 0:
+        print(f"File '{path}':")
+
+        for img in img_list:
+            print(
+                f"    Line {img[1].line}: '{img[0].named_params['filename']}'"
+            )
+
+    return len(img_list)
+
+
+parser = argparse.ArgumentParser(
+    "Image report",
+    "Scans a folder and report all Hugo image shortcodes found"
+)
+
+parser.add_argument("pathname", help="Path of the folder to scan")
+
+args = parser.parse_args()
+
+print(f"Scanning '{args.pathname}'")
+
+num_found = 0
+
+for root, dirs, files in os.walk(args.pathname):
+    for file in files:
+        if file.endswith(".md"):
+            fullpath = os.path.join(root, file)
+            num_found += scan_file(fullpath)
+
+if num_found == 0:
+    print(f"No image shortcodes found in '{args.pathname}'")
+else:
+    print(f"Found {num_found} image shortcodes.")

build/pylibs/hugotools.py

@@ -0,0 +1,155 @@
+from enum import Enum
+from typing import Iterator, Match, Callable
+
+import re
+
+
+class TextPosInfo:
+    line: int
+    start: int
+    end: int
+
+    def __init__(self, line, start, end):
+        self.line = line
+        self.start = start
+        self.end = end
+
+
+shortcode_re_pattern_start = r"(\n)|\{\{[<%]\s*"
+shortcode_re_body = r"(/)?([\w\-]+)\s*(.+?)?"
+shortcode_re_pattern_end = r"\s*[>%]\}\}"
+
+shortcode_re_pattern = (
+    shortcode_re_pattern_start +
+    shortcode_re_body +
+    shortcode_re_pattern_end
+)
+
+
+class ShortcodeTagType(Enum):
+    """Specifies open or close shortcode tag."""
+    OPEN = 1
+    CLOSE = 2
+
+
+class ShortcodeInfo:
+    """Represents the information in a shortcode.
+    """
+    tag_type: ShortcodeTagType
+    tag: str
+    pos_params: list[str]
+    named_params: dict[str, str]
+
+    def parse_params(self, param_str: str):
+        param_re = "|".join([
+            r'"(([^"]|(?<=\\)")*)"',
+            r'((\w+)=([^"\s]+))',
+            r'((\w+)="(([^"]|(?<=\\)")*)")',
+            r'([^"=\s]+)'
+        ])
+
+        for match in re.finditer(param_re, param_str):
+            if match is None:
+                self.pos_params = []
+                self.named_params = {}
+                return
+
+            if match[1]:
+                self.pos_params.append(re.sub(r'\\"', '"', match[1]))
+            elif match[3]:
+                self.named_params[match[4]] = match[5]
+            elif match[6]:
+                self.named_params[match[7]] = re.sub(r'\\"', '"', match[8])
+            elif match[10]:
+                self.pos_params.append(match[10])
+
+    def __init__(
+            self, tag: str,
+            tag_type: ShortcodeTagType,
+            param_text: str = ""
+    ):
+        self.tag = tag
+        self.tag_type = tag_type
+        self.pos_params = []
+        self.named_params = {}
+        self.parse_params(param_text or "")
+
+    def __str__(self) -> str:
+        type_text: str
+
+        if self.tag_type == ShortcodeTagType.OPEN:
+            type_text = "OPEN"
+        else:
+            type_text = "CLOSE"
+
+        result = f"{type_text} {self.tag}"
+
+        if self.pos_params or self.named_params:
+            result += ":"
+
+        for pos_param in self.pos_params:
+            result += f"\n    '{pos_param}'"
+
+        for named_param, named_value in self.named_params.items():
+            result += f"\n    {named_param} = {named_value}"
+
+        return result
+
+
+class ShortcodeIterator:
+    """Iterates through all shortcodes in a string.
+    """
+    re_iterator: Iterator[Match[str]]
+    linenum: int
+    sc_filter: Callable[[ShortcodeInfo], bool]
+
+    def __init__(
+            self,
+            text: str,
+            sc_filter: Callable[[ShortcodeInfo], bool] = lambda x: True
+    ):
+        self.re_iterator = re.finditer(shortcode_re_pattern, text)
+        self.sc_filter = lambda self, x: sc_filter(x)
+        self.linenum = 1
+
+    def __iter__(self):
+        return self
+
+    def __next__(self) -> tuple[ShortcodeInfo, TextPosInfo]:
+        next_match = self.re_iterator.__next__()
+
+        while True:
+            if next_match[1]:
+                self.linenum += 1
+            elif next_match[2]:
+                result = ShortcodeInfo(
+                    next_match[3], ShortcodeTagType.CLOSE
+                )
+
+                if self.sc_filter(self, result):
+                    return (
+                        result,
+                        TextPosInfo(
+                            self.linenum,
+                            next_match.start(),
+                            next_match.end()
+                        )
+                    )
+            else:
+                result = ShortcodeInfo(
+                    next_match[3],
+                    ShortcodeTagType.OPEN,
+                    next_match[4]
+                )
+
+                if self.sc_filter(self, result):
+                    return (
+                        result,
+                        TextPosInfo(
+                            self.linenum,
+                            next_match.start(),
+                            next_match.end()
+                        )
+                    )
+
+            next_match = self.re_iterator.__next__()

content/develop/clients/go/queryjson.md

@@ -102,6 +102,13 @@ Specify query options to return only the `city` field:
 {{< clients-example go_home_json query2 >}}
 {{< /clients-example >}}
 
+You can also use the same query with the `CountOnly` option
+enabled to get the number of documents found without
+returning the documents themselves.
+
+{{< clients-example go_home_json query2count_only >}}
+{{< /clients-example >}}
+
 Use an
 [aggregation query]({{< relref "/develop/interact/search-and-query/query/aggregation" >}})
 to count all users in each city.

content/develop/clients/nodejs/connect.md

@@ -67,7 +67,7 @@ createClient({
 ```
 To check if the client is connected and ready to send commands, use `client.isReady`, which returns a Boolean. `client.isOpen` is also available. This returns `true` when the client's underlying socket is open, and `false` when it isn't (for example, when the client is still connecting or reconnecting after a network error).
 
-### Connect to a Redis cluster
+## Connect to a Redis cluster
 
 To connect to a Redis cluster, use `createCluster`.
 
@@ -97,7 +97,7 @@ console.log(value); // returns 'bar'
 await cluster.quit();
 ```
 
-### Connect to your production Redis with TLS
+## Connect to your production Redis with TLS
 
 When you deploy your application, use TLS and follow the [Redis security]({{< relref "/operate/oss_and_stack/management/security/" >}}) guidelines.
 
@@ -127,3 +127,77 @@ await client.disconnect();
 ```
 
 You can also use discrete parameters and UNIX sockets. Details can be found in the [client configuration guide](https://github.com/redis/node-redis/blob/master/docs/client-configuration.md).
+
+## Reconnect after disconnection
+
+By default, `node-redis` doesn't attempt to reconnect automatically when
+the connection to the server is lost. However, you can set the
+`socket.reconnectionStrategy` field in the configuration to decide
+whether to try to reconnect and how to approach it. Choose one of the following values for
+`socket.reconnectionStrategy`:
+
+-   `false`: (Default) Don't attempt to reconnect.
+-   `number`: Wait for this number of milliseconds and then attempt to reconnect.
+-   `<function>`: Use a custom
+    function to decide how to handle reconnection.
+
+The custom function has the following signature:
+
+```js
+(retries: number, cause: Error) => false | number | Error
+```
+
+It is called before each attempt to reconnect, with the `retries`
+indicating how many attempts have been made so far. The `cause` parameter is an
+[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
+object with information about how the connection was lost. The return value
+from the function can be any of the following:
+
+-   `false`: Don't attempt to reconnect.
+-   `number`: Wait this number of milliseconds and then try again.
+-   `Error`: Same as `false`, but lets you supply extra information about why
+    no attempt was made to reconnect.
+
+The example below shows a `reconnectionStrategy` function that implements a
+custom [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)
+strategy:
+
+```js
+createClient({
+  socket: {
+    reconnectStrategy: retries => {
+        // Generate a random jitter between 0 – 200 ms:
+        const jitter = Math.floor(Math.random() * 200);
+
+        // Delay is an exponential back off, (times^2) * 50 ms, with a
+        // maximum value of 2000 ms:
+        const delay = Math.min(Math.pow(2, retries) * 50, 2000);
+
+        return delay + jitter;
+    }
+  }
+});
+```
+
+## Connection events
+
+The client object emits the following
+[events](https://developer.mozilla.org/en-US/docs/Web/API/Event) that are
+related to connection:
+
+-   `connect`: (No parameters) The client is about to start connecting to the server.
+-   `ready`: (No parameters) The client has connected and is ready to use.
+-   `end`: (No parameters) The client has been intentionally closed using `client.quit()`.
+-   `error`: An error has occurred, which is described by the
+    [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
+    parameter. This is usually a network issue such as "Socket closed unexpectedly".
+-   `reconnecting`: (No parameters) The client is about to try reconnecting after the
+    connection was lost due to an error.
+
+Use code like the following to respond to these events:
+
+```js
+client.on('error', error => {
+    console.error(`Redis client error:`, error);
+});
+```