From 51688ce6294eebc65a3b120f1ae7e317981f82d3 Mon Sep 17 00:00:00 2001 From: "Chayim I. Kirshen" Date: Mon, 16 May 2022 15:24:59 +0300 Subject: [PATCH 1/4] CLIENT COMMAND spec --- formats/CLIENT_COMMANDS.md | 60 ++++++++++++++++++++++++++++++++++++++ formats/README.md | 1 + 2 files changed, 61 insertions(+) create mode 100644 formats/CLIENT_COMMANDS.md create mode 100644 formats/README.md diff --git a/formats/CLIENT_COMMANDS.md b/formats/CLIENT_COMMANDS.md new file mode 100644 index 0000000..93e5b7d --- /dev/null +++ b/formats/CLIENT_COMMANDS.md @@ -0,0 +1,60 @@ +# Redis Client Library Command Specification + +Redis client libraries provide helper functions for communicating with Redis. This specification exists to describe the format of the file used by redis clients, to communicate their function usage with Redis. + +## Implementation + +To implement this specification, a file named *functions.json* must be created at the root of the client repository. *functions.json* is a json formatted file containing links to generated documentation, and optionally examples. + +The following is the basic example of the *functions.json* specification. + +:: + { + "name": "redis-py", + "language": "python", + "metadata": { + "repository": "https://github.com/redis/redis-py", + "issues_url": "https://github.com/redis/redis-py/issues", + }, + "commands": { + "SET": { + "uri": "https://redis.readthedocs.io/en/latest/commands.html#redis.commands.core.CoreCommands.set", + "example": [ + "import redis", + "r = redis.Redis()", + "r.set('foo', 'bar)", + ], + "added": "2.0", + "history": [ + "4.0.0", + "Added support for exat expiration flag", + "https://github.com/redis/redis-py/releases/tag/v4.0.0", + ], + }, + "GET": { + "uri": "https://redis.readthedocs.io/en/latest/commands.html#redis.commands.core.CoreCommands.get", + "example": [ + "import redis", + "r = redis.Redis()", + "r.get('foo')", + ], + "added": "2.0", + }, + } + } + +## Field Descriptions + +* name - This is the name of client library +* language - The language of the client library + +* metadata - A list of urls comprising of: + * repository - A link to the source code for the Redis client library + * issues_url - A link to open tickets for the client library + +* commands - A map of commands, keyed to the redis command name, with links to their respective documentation. + + * uri - The link to the documentation for the associated redis command + * example *(Optional)* - A list of strings, comprising of an example of the function usage + * added *(Optional)* - The version of the client library containing this function + * history *(Optional)* - A list of changes. \ No newline at end of file diff --git a/formats/README.md b/formats/README.md new file mode 100644 index 0000000..f5ed489 --- /dev/null +++ b/formats/README.md @@ -0,0 +1 @@ +# Redis Data Format Specifications From d68d484851efcd42b8b52477c35bf370e4842c50 Mon Sep 17 00:00:00 2001 From: "Chayim I. Kirshen" Date: Wed, 18 May 2022 10:35:41 +0300 Subject: [PATCH 2/4] fixing python example --- formats/CLIENT_COMMANDS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/formats/CLIENT_COMMANDS.md b/formats/CLIENT_COMMANDS.md index 93e5b7d..09b9384 100644 --- a/formats/CLIENT_COMMANDS.md +++ b/formats/CLIENT_COMMANDS.md @@ -1,6 +1,6 @@ # Redis Client Library Command Specification -Redis client libraries provide helper functions for communicating with Redis. This specification exists to describe the format of the file used by redis clients, to communicate their function usage with Redis. +Redis client libraries provide helper functions for communicating with Redis. This specification exists to describe the format of the file used by redis clients, to communicate their function usage with Redis. ## Implementation @@ -22,7 +22,7 @@ The following is the basic example of the *functions.json* specification. "example": [ "import redis", "r = redis.Redis()", - "r.set('foo', 'bar)", + "r.set('foo', 'bar')", ], "added": "2.0", "history": [ @@ -44,7 +44,7 @@ The following is the basic example of the *functions.json* specification. } ## Field Descriptions - + * name - This is the name of client library * language - The language of the client library @@ -52,9 +52,9 @@ The following is the basic example of the *functions.json* specification. * repository - A link to the source code for the Redis client library * issues_url - A link to open tickets for the client library -* commands - A map of commands, keyed to the redis command name, with links to their respective documentation. +* commands - A map of commands, keyed to the redis command name, with links to their respective documentation. * uri - The link to the documentation for the associated redis command * example *(Optional)* - A list of strings, comprising of an example of the function usage * added *(Optional)* - The version of the client library containing this function - * history *(Optional)* - A list of changes. \ No newline at end of file + * history *(Optional)* - A list of changes. From 8464e22786f2d091068bacd95f9704222e58a821 Mon Sep 17 00:00:00 2001 From: "Chayim I. Kirshen" Date: Wed, 18 May 2022 15:06:45 +0300 Subject: [PATCH 3/4] pr comments --- formats/CLIENT_COMMANDS.md | 51 ++++++++++++++++++++++++-------------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/formats/CLIENT_COMMANDS.md b/formats/CLIENT_COMMANDS.md index 09b9384..4507ccd 100644 --- a/formats/CLIENT_COMMANDS.md +++ b/formats/CLIENT_COMMANDS.md @@ -4,9 +4,9 @@ Redis client libraries provide helper functions for communicating with Redis. Th ## Implementation -To implement this specification, a file named *functions.json* must be created at the root of the client repository. *functions.json* is a json formatted file containing links to generated documentation, and optionally examples. +To implement this specification, a file named *usage.json* must be created at the root of the client repository. *usage.json* is a json formatted file containing links to generated documentation, and optionally examples. -The following is the basic example of the *functions.json* specification. +The following is the basic example of the *usage.json* specification. :: { @@ -14,32 +14,39 @@ The following is the basic example of the *functions.json* specification. "language": "python", "metadata": { "repository": "https://github.com/redis/redis-py", - "issues_url": "https://github.com/redis/redis-py/issues", + "issues_url": "https://github.com/redis/redis-py/issues" }, "commands": { "SET": { "uri": "https://redis.readthedocs.io/en/latest/commands.html#redis.commands.core.CoreCommands.set", - "example": [ - "import redis", - "r = redis.Redis()", - "r.set('foo', 'bar')", + "examples": [ + { + "name": "Redis Set Example", + "description": "The following is an example of setting a key in redis.", + "example": "import redis\nr=redis.Redis()\nr.set('foo', 'bar')", + "explanation": "In our example, a key named foo, is set to the value bar." + } ], "added": "2.0", "history": [ - "4.0.0", - "Added support for exat expiration flag", - "https://github.com/redis/redis-py/releases/tag/v4.0.0", - ], + { + "version": "4.0.0", + "note": "Added support for exat expiration flag", + "release Notes": "https://github.com/redis/redis-py/releases/tag/v4.0.0" + } + ] }, "GET": { "uri": "https://redis.readthedocs.io/en/latest/commands.html#redis.commands.core.CoreCommands.get", "example": [ - "import redis", - "r = redis.Redis()", - "r.get('foo')", + { + "name": "Get Example", + "description": "The following is an example of retrieving a key named foo, already set in redis.", + "example": "import redis\nr = redis.Redis()r.get('foo')" + } ], - "added": "2.0", - }, + "added": "2.0" + } } } @@ -55,6 +62,14 @@ The following is the basic example of the *functions.json* specification. * commands - A map of commands, keyed to the redis command name, with links to their respective documentation. * uri - The link to the documentation for the associated redis command - * example *(Optional)* - A list of strings, comprising of an example of the function usage + * examples *(Optional)* - A list of dictionaries, each comprising of an example of the function usage. Each dictionary contains the following elements: + * name - A name describing what the example does + * description - A brief description of the example + * example - A plain text entry containing the example. Newlines + * explanation *(Optional)* - Text describing in depth, what the example does. + * added *(Optional)* - The version of the client library containing this function - * history *(Optional)* - A list of changes. + * history *(Optional)* - A list of dictionaries containing change history. Each dictionary contains the following elements: + * version - The client version containing this change + * note - A plain text description of the change + * release notes *(Optional)* - A link to release notes for specified client version From 39d0e39e21f8b80c41c986117ed92006c78e0d35 Mon Sep 17 00:00:00 2001 From: "Chayim I. Kirshen" Date: Wed, 18 May 2022 16:31:18 +0300 Subject: [PATCH 4/4] key change --- formats/CLIENT_COMMANDS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/formats/CLIENT_COMMANDS.md b/formats/CLIENT_COMMANDS.md index 4507ccd..6505449 100644 --- a/formats/CLIENT_COMMANDS.md +++ b/formats/CLIENT_COMMANDS.md @@ -32,7 +32,7 @@ The following is the basic example of the *usage.json* specification. { "version": "4.0.0", "note": "Added support for exat expiration flag", - "release Notes": "https://github.com/redis/redis-py/releases/tag/v4.0.0" + "releasenotes": "https://github.com/redis/redis-py/releases/tag/v4.0.0" } ] }, @@ -65,7 +65,7 @@ The following is the basic example of the *usage.json* specification. * examples *(Optional)* - A list of dictionaries, each comprising of an example of the function usage. Each dictionary contains the following elements: * name - A name describing what the example does * description - A brief description of the example - * example - A plain text entry containing the example. Newlines + * example - A plain text entry containing the example. Newlines * explanation *(Optional)* - Text describing in depth, what the example does. * added *(Optional)* - The version of the client library containing this function