From af1f22cdb5e557358e58aa677f0f177fd465f229 Mon Sep 17 00:00:00 2001 From: Kurt McKee Date: Thu, 18 Jul 2024 09:49:17 -0500 Subject: [PATCH] Resolve some docs warnings (#3322) Get rid of some warning related to documentation. --- .github/wordlist.txt | 1 + docs/conf.py | 1 - docs/connections.rst | 6 ++--- docs/opentelemetry.rst | 8 +++---- redis/commands/core.py | 27 +++++++++++++--------- redis/commands/graph/commands.py | 2 +- redis/commands/search/commands.py | 38 +++++++++++++++---------------- 7 files changed, 44 insertions(+), 39 deletions(-) diff --git a/.github/wordlist.txt b/.github/wordlist.txt index 540e915277..ca2102b825 100644 --- a/.github/wordlist.txt +++ b/.github/wordlist.txt @@ -141,3 +141,4 @@ unicode url virtualenv www +yaml diff --git a/docs/conf.py b/docs/conf.py index f66c5903ff..865bd522a2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -128,7 +128,6 @@ # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - "display_version": True, "footer_icons": [ { "name": "GitHub", diff --git a/docs/connections.rst b/docs/connections.rst index 1c826a0cf8..b547a7659e 100644 --- a/docs/connections.rst +++ b/docs/connections.rst @@ -55,7 +55,7 @@ ClusterNode Async Client ************ -See complete example: `here `_ +See complete example: `here `__ This client is used for communicating with Redis, asynchronously. @@ -88,7 +88,7 @@ ClusterPipeline (Async) Connection ********** -See complete example: `here `_ +See complete example: `here `__ Connection ========== @@ -104,7 +104,7 @@ Connection (Async) Connection Pools **************** -See complete example: `here `_ +See complete example: `here `__ ConnectionPool ============== diff --git a/docs/opentelemetry.rst b/docs/opentelemetry.rst index d006a60461..c0285e6761 100644 --- a/docs/opentelemetry.rst +++ b/docs/opentelemetry.rst @@ -4,7 +4,7 @@ Integrating OpenTelemetry What is OpenTelemetry? ---------------------- -`OpenTelemetry `_ is an open-source observability framework for traces, metrics, and logs. It is a merger of OpenCensus and OpenTracing projects hosted by Cloud Native Computing Foundation. +`OpenTelemetry `__ is an open-source observability framework for traces, metrics, and logs. It is a merger of OpenCensus and OpenTracing projects hosted by Cloud Native Computing Foundation. OpenTelemetry allows developers to collect and export telemetry data in a vendor agnostic way. With OpenTelemetry, you can instrument your application once and then add or change vendors without changing the instrumentation, for example, here is a list of `popular DataDog competitors `_ that support OpenTelemetry. @@ -61,7 +61,7 @@ Once the code is patched, you can use redis-py as usually: OpenTelemetry API ----------------- -`OpenTelemetry `_ API is a programming interface that you can use to instrument code and collect telemetry data such as traces, metrics, and logs. +`OpenTelemetry API `__ is a programming interface that you can use to instrument code and collect telemetry data such as traces, metrics, and logs. You can use OpenTelemetry API to measure important operations: @@ -125,7 +125,7 @@ Alerting and notifications Uptrace also allows you to monitor `OpenTelemetry metrics `_ using alerting rules. For example, the following monitor uses the group by node expression to create an alert whenever an individual Redis shard is down: -.. code-block:: python +.. code-block:: yaml monitors: - name: Redis shard is down @@ -142,7 +142,7 @@ Uptrace also allows you to monitor `OpenTelemetry metrics ResponseT: """ - Delete the ACL for the specified ``username``s + Delete the ACL for the specified ``username``\\s For more information see https://redis.io/commands/acl-deluser """ @@ -227,9 +227,10 @@ def acl_setuser( must be prefixed with either a '+' to add the command permission or a '-' to remove the command permission. keys: A list of key patterns to grant the user access to. Key patterns allow - '*' to support wildcard matching. For example, '*' grants access to - all keys while 'cache:*' grants access to all keys that are prefixed - with 'cache:'. `keys` should not be prefixed with a '~'. + ``'*'`` to support wildcard matching. For example, ``'*'`` grants + access to all keys while ``'cache:*'`` grants access to all keys that + are prefixed with ``cache:``. + `keys` should not be prefixed with a ``'~'``. reset: Indicates whether the user should be fully reset prior to applying the new ACL. Setting this to `True` will remove all existing passwords, flags, and privileges from the user and then apply the @@ -3366,7 +3367,7 @@ def sintercard( self, numkeys: int, keys: List[str], limit: int = 0 ) -> Union[Awaitable[int], int]: """ - Return the cardinality of the intersect of multiple sets specified by ``keys`. + Return the cardinality of the intersect of multiple sets specified by ``keys``. When LIMIT provided (defaults to 0 and means unlimited), if the intersection cardinality reaches limit partway through the computation, the algorithm will @@ -3498,9 +3499,11 @@ class StreamCommands(CommandsProtocol): def xack(self, name: KeyT, groupname: GroupT, *ids: StreamIdT) -> ResponseT: """ Acknowledges the successful processing of one or more messages. - name: name of the stream. - groupname: name of the consumer group. - *ids: message ids to acknowledge. + + Args: + name: name of the stream. + groupname: name of the consumer group. + *ids: message ids to acknowledge. For more information see https://redis.io/commands/xack """ @@ -3696,8 +3699,10 @@ def xclaim( def xdel(self, name: KeyT, *ids: StreamIdT) -> ResponseT: """ Deletes one or more messages from a stream. - name: name of the stream. - *ids: message ids to delete. + + Args: + name: name of the stream. + *ids: message ids to delete. For more information see https://redis.io/commands/xdel """ @@ -4265,7 +4270,7 @@ def zintercard( ) -> Union[Awaitable[int], int]: """ Return the cardinality of the intersect of multiple sorted sets - specified by ``keys`. + specified by ``keys``. When LIMIT provided (defaults to 0 and means unlimited), if the intersection cardinality reaches limit partway through the computation, the algorithm will exit and yield limit as the cardinality diff --git a/redis/commands/graph/commands.py b/redis/commands/graph/commands.py index 762ab42e16..d92018f731 100644 --- a/redis/commands/graph/commands.py +++ b/redis/commands/graph/commands.py @@ -155,7 +155,7 @@ def slowlog(self): def config(self, name, value=None, set=False): """ Retrieve or update a RedisGraph configuration. - For more information see `https://redis.io/commands/graph.config-get/>`_. # noqa + For more information see ``__. Args: diff --git a/redis/commands/search/commands.py b/redis/commands/search/commands.py index 6a828c7e62..da79016ad4 100644 --- a/redis/commands/search/commands.py +++ b/redis/commands/search/commands.py @@ -337,30 +337,30 @@ def add_document( """ Add a single document to the index. - ### Parameters + Args: - - **doc_id**: the id of the saved document. - - **nosave**: if set to true, we just index the document, and don't + doc_id: the id of the saved document. + nosave: if set to true, we just index the document, and don't save a copy of it. This means that searches will just return ids. - - **score**: the document ranking, between 0.0 and 1.0 - - **payload**: optional inner-index payload we can save for fast - i access in scoring functions - - **replace**: if True, and the document already is in the index, - we perform an update and reindex the document - - **partial**: if True, the fields specified will be added to the + score: the document ranking, between 0.0 and 1.0 + payload: optional inner-index payload we can save for fast + access in scoring functions + replace: if True, and the document already is in the index, + we perform an update and reindex the document + partial: if True, the fields specified will be added to the existing document. This has the added benefit that any fields specified with `no_index` will not be reindexed again. Implies `replace` - - **language**: Specify the language used for document tokenization. - - **no_create**: if True, the document is only updated and reindexed + language: Specify the language used for document tokenization. + no_create: if True, the document is only updated and reindexed if it already exists. If the document does not exist, an error will be returned. Implies `replace` - - **fields** kwargs dictionary of the document fields to be saved - and/or indexed. - NOTE: Geo points shoule be encoded as strings of "lon,lat" + fields: kwargs dictionary of the document fields to be saved + and/or indexed. + NOTE: Geo points shoule be encoded as strings of "lon,lat" """ # noqa return self._add_document( doc_id, @@ -627,13 +627,13 @@ def spellcheck(self, query, distance=None, include=None, exclude=None): """ Issue a spellcheck query - ### Parameters + Args: - **query**: search query. - **distance***: the maximal Levenshtein distance for spelling + query: search query. + distance: the maximal Levenshtein distance for spelling suggestions (default: 1, max: 4). - **include**: specifies an inclusion custom dictionary. - **exclude**: specifies an exclusion custom dictionary. + include: specifies an inclusion custom dictionary. + exclude: specifies an exclusion custom dictionary. For more information see `FT.SPELLCHECK `_. """ # noqa