From 40abf7708fe58ef754466ef67a8317a21e1040b0 Mon Sep 17 00:00:00 2001 From: Nate Anderson Date: Tue, 16 Jan 2024 12:16:06 -0800 Subject: [PATCH] chore: add Kotlin docs --- .../cache/develop/sdks/kotlin/cheat-sheet.mdx | 79 +++++++++++++++++++ docs/cache/develop/sdks/kotlin/index.md | 31 ++++++++ docs/cache/getting-started.md | 1 + docs/cache/index.md | 1 + docs/topics/develop/sdks/kotlin/index.md | 29 +++++++ docusaurus.config.js | 2 +- .../api-support-matrix-generator.ts | 11 +++ .../src/examples/examples.ts | 3 + .../resolvers/sdk-repo-snippet-resolver.ts | 5 ++ .../languages/dart-snippet-source-parser.ts | 2 +- .../languages/kotlin-snippet-source-parser.ts | 36 +++++++++ .../sdk-github-repo-source-provider.ts | 2 + .../src/examples/sdk-source/sdks.ts | 3 + .../src/inject-example-code-snippets.ts | 2 + src/components/SdkExampleFileTabs/index.jsx | 2 +- .../SdkExampleFileTabsImpl/index.jsx | 9 ++- src/components/SdkExampleTabsImpl/index.jsx | 9 ++- 17 files changed, 220 insertions(+), 7 deletions(-) create mode 100644 docs/cache/develop/sdks/kotlin/cheat-sheet.mdx create mode 100644 docs/cache/develop/sdks/kotlin/index.md create mode 100644 docs/topics/develop/sdks/kotlin/index.md create mode 100644 plugins/example-code-snippets/src/examples/resolvers/source-parsers/languages/kotlin-snippet-source-parser.ts diff --git a/docs/cache/develop/sdks/kotlin/cheat-sheet.mdx b/docs/cache/develop/sdks/kotlin/cheat-sheet.mdx new file mode 100644 index 0000000000..6b735ea9f9 --- /dev/null +++ b/docs/cache/develop/sdks/kotlin/cheat-sheet.mdx @@ -0,0 +1,79 @@ +--- +sidebar_position: 1 +sidebar_label: Cheat Sheet +title: Cheat Sheet for Kotlin +description: Get started really quickly coding using Kotlin with Momento Cache +--- + +import { SdkExampleCodeBlock } from "@site/src/components/SdkExampleCodeBlock"; +// This import is necessary even though it looks like it's un-used; The inject-example-code-snippet +// plugin will transform instances of SdkExampleCodeBlock to SdkExampleCodeBlockImpl +import { SdkExampleCodeBlockImpl } from "@site/src/components/SdkExampleCodeBlockImpl"; + +# Cheat Sheet for Kotlin with Momento Cache + +If you need to get going quickly with Kotlin and Momento Cache, this page contains the basic API calls you'll need. [Check the Kotlin SDK examples](https://github.com/momentohq/client-sdk-kotlin/tree/main/examples) for complete, working examples including build configuration files. + +## Install the Momento client library + +Install the client library in an existing Kotlin project: + +### Gradle + +```kotlin +implementation("software.momento.kotlin:sdk:0.1.3") +``` + +### Maven + +```xml + + software.momento.kotlin + sdk + 0.1.3 + +``` + +## Set up your auth token + +You'll need a Momento API key to authenticate with Momento. You can get one from the [Momento Web Console](https://console.gomomento.com/caches). +Once you have your token, store it in an environment variable so that the Momento client can consume it: + +``` +export MOMENTO_API_KEY= +``` + +## Import libraries and connect to return a CacheClient object +This code sets up the main function, the necessary imports, and the CacheClient instantiation that each of the other functions will need to call. + + + +## Create a new cache in Momento Cache +Use this function to create a new cache in your account. + + + + +## List the names of existing caches in your account +A simple list of the names of caches for the account. + + + +## Write an item to a cache +A simple example of doing a set operation. In the client.set call, the TTL it optional. If you did pass it in, this would override the default TTL value set with the client connection object. + + + +## Read an item from a cache +This is an example of a simple read operation to get an item from a cache. + + + +## Running the code + +You can find complete, working examples in the [Kotlin SDK github repo examples directory](https://github.com/momentohq/client-sdk-kotlin/tree/main/examples). + +:::info +Beyond these basic API calls check out the [API reference page](/cache/develop/api-reference/index.mdx) for more information on the full assortment of Momento API calls. + +::: diff --git a/docs/cache/develop/sdks/kotlin/index.md b/docs/cache/develop/sdks/kotlin/index.md new file mode 100644 index 0000000000..01db2bdaae --- /dev/null +++ b/docs/cache/develop/sdks/kotlin/index.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 6 +title: Momento Kotlin SDK +pagination_prev: null +sidebar_label: Kotlin +description: Information about the Momento Kotlin SDK +--- + +# Momento Kotlin SDK + +The Momento Kotlin SDK for Android and JVM is available via Maven Central: [`software.momento.kotlin:sdk`](https://central.sonatype.com/artifact/software.momento.kotlin/sdk). + + +The source code can be found on GitHub: [momentohq/client-sdk-kotlin](https://github.com/momentohq/client-sdk-kotlin). + +## Requirements + +- A Momento API Key is required; you can get one from the [Momento Web Console](https://console.gomomento.com/). +- At least the Java 11 run time installed, or Android 23+. +- mvn or gradle for downloading the sdk. + +## Resources + +- [Kotlin SDK Cheat Sheet](./cheat-sheet.mdx) +- [Kotlin SDK Examples](https://github.com/momentohq/client-sdk-kotlin/blob/main/examples/README.md): working example projects that illustrate how to use the Kotlin SDK +- COMING SOON: Observability: Logging and Client-side Metrics with the Kotlin SDK +- COMING SOON: Taking your code to prod: Configuration and Error handling in the Kotlin SDK + +## Integrations + +COMING SOON diff --git a/docs/cache/getting-started.md b/docs/cache/getting-started.md index 8b6fce7834..42a2e702ef 100644 --- a/docs/cache/getting-started.md +++ b/docs/cache/getting-started.md @@ -175,6 +175,7 @@ We currently have the following SDK languages available: - [Go](./develop/sdks/go) - [PHP](./develop/sdks/php) - [Java](./develop/sdks/java) +- [Kotlin](./develop/sdks/kotlin) - [Rust](./develop/sdks/rust) - [Ruby](./develop/sdks/ruby) - [Elixir](./develop/sdks/elixir) diff --git a/docs/cache/index.md b/docs/cache/index.md index b9b3dc72ef..425d2d8c82 100644 --- a/docs/cache/index.md +++ b/docs/cache/index.md @@ -40,6 +40,7 @@ In the following pages, you can learn about caching in general and how to use Mo - [Go](./cache/develop/sdks/go) - [PHP](./cache/develop/sdks/php) - [Java](./cache/develop/sdks/java) + - [Kotlin](./cache/develop/sdks/kotlin) - [Rust](./cache/develop/sdks/rust) - [Ruby](./cache/develop/sdks/ruby) - [Elixir](./cache/develop/sdks/elixir) diff --git a/docs/topics/develop/sdks/kotlin/index.md b/docs/topics/develop/sdks/kotlin/index.md new file mode 100644 index 0000000000..c90c2fd7d6 --- /dev/null +++ b/docs/topics/develop/sdks/kotlin/index.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 6 +title: Momento Kotlin SDK +pagination_prev: null +sidebar_label: Kotlin +description: Information about the Momento Kotlin SDK +--- + +# Momento Kotlin SDK + +The Momento Kotlin SDK is available via Maven Central: [`software.momento.kotlin:sdk`](https://central.sonatype.com/artifact/software.momento.kotlin/sdk). + +The source code can be found on GitHub: [momentohq/client-sdk-kotlin](https://github.com/momentohq/client-sdk-kotlin). + +## Requirements + +- A Momento API key is required; you can get one from the [Momento Web Console](https://console.gomomento.com/). +- At least the Java 11 run time installed or Android 23+ +- mvn or gradle for downloading the sdk + +## Resources + +- [Kotlin SDK Examples](https://github.com/momentohq/client-sdk-kotlin/blob/main/examples/README.md): working example projects that illustrate how to use the Kotlin SDK +- COMING SOON: Observability: Logging and Client-side Metrics with the Kotlin SDK +- COMING SOON: Taking your code to prod: Configuration and Error handling in the Kotlin SDK + +## Integrations + +COMING SOON diff --git a/docusaurus.config.js b/docusaurus.config.js index b4d431e60c..d5fb6a1522 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -376,7 +376,7 @@ const config = { ], }, prism: { - additionalLanguages: ["java", "rust", "csharp", "php", "elixir", "swift", "dart"], + additionalLanguages: ["java", "kotlin", "rust", "csharp", "php", "elixir", "swift", "dart"], theme: lightCodeTheme, darkTheme: darkCodeTheme, }, diff --git a/plugins/example-code-snippets/src/api-support/api-support-matrix-generator.ts b/plugins/example-code-snippets/src/api-support/api-support-matrix-generator.ts index b66f6405cb..437ae27bea 100644 --- a/plugins/example-code-snippets/src/api-support/api-support-matrix-generator.ts +++ b/plugins/example-code-snippets/src/api-support/api-support-matrix-generator.ts @@ -81,6 +81,17 @@ const SDKS: Array = [ authClientFile: 'momento-sdk/src/main/java/momento/sdk/AuthClient.java', leaderboardClientFile: undefined, }, + { + sdk: Sdk.KOTLIN, + cacheClientFile: + 'src/commonMain/kotlin/software/momento/kotlin/sdk/CacheClient.kt', + configObjectFile: + 'src/commonMain/kotlin/software/momento/kotlin/sdk/config/Configuration.kt', + topicClientFile: + 'src/commonMain/kotlin/software/momento/kotlin/sdk/TopicClient.kt', + authClientFile: undefined, + leaderboardClientFile: undefined, + }, { sdk: Sdk.ELIXIR, cacheClientFile: 'src/lib/momento/cache_client.ex', diff --git a/plugins/example-code-snippets/src/examples/examples.ts b/plugins/example-code-snippets/src/examples/examples.ts index 2b74af4989..fddf1d163d 100644 --- a/plugins/example-code-snippets/src/examples/examples.ts +++ b/plugins/example-code-snippets/src/examples/examples.ts @@ -10,6 +10,7 @@ export enum ExampleLanguage { PYTHON = 'python', GO = 'go', JAVA = 'java', + KOTLIN = 'kotlin', PHP = 'php', RUST = 'rust', RUBY = 'ruby', @@ -48,6 +49,8 @@ export function languageDisplayName(language: ExampleLanguage): string { return 'Go'; case ExampleLanguage.JAVA: return 'Java'; + case ExampleLanguage.KOTLIN: + return 'Kotlin'; case ExampleLanguage.PHP: return 'PHP'; case ExampleLanguage.RUST: diff --git a/plugins/example-code-snippets/src/examples/resolvers/sdk-repo-snippet-resolver.ts b/plugins/example-code-snippets/src/examples/resolvers/sdk-repo-snippet-resolver.ts index 3257a192e9..d996a076dc 100644 --- a/plugins/example-code-snippets/src/examples/resolvers/sdk-repo-snippet-resolver.ts +++ b/plugins/example-code-snippets/src/examples/resolvers/sdk-repo-snippet-resolver.ts @@ -14,6 +14,7 @@ import {JavaSnippetSourceParser} from './source-parsers/languages/java-snippet-s import {ElixirSnippetSourceParser} from './source-parsers/languages/elixir-snippet-source-parser'; import {SwiftSnippetSourceParser} from './source-parsers/languages/swift-snippet-source-parser'; import {DartSnippetSourceParser} from './source-parsers/languages/dart-snippet-source-parser'; +import {KotlinSnippetSourceParser} from './source-parsers/languages/kotlin-snippet-source-parser'; export class SdkRepoSnippetResolver implements SnippetResolver { private readonly sourceProvider: SdkSourceProvider = @@ -87,6 +88,8 @@ export class SdkRepoSnippetResolver implements SnippetResolver { return new GolangSnippetSourceParser(sourceDir); case ExampleLanguage.JAVA: return new JavaSnippetSourceParser(sourceDir); + case ExampleLanguage.KOTLIN: + return new KotlinSnippetSourceParser(sourceDir); case ExampleLanguage.PHP: return new PhpSnippetSourceParser(sourceDir); case ExampleLanguage.ELIXIR: @@ -122,6 +125,8 @@ function sdkForLanguage(language: ExampleLanguage): Sdk { return Sdk.GO; case ExampleLanguage.JAVA: return Sdk.JAVA; + case ExampleLanguage.KOTLIN: + return Sdk.KOTLIN; case ExampleLanguage.PHP: return Sdk.PHP; case ExampleLanguage.RUST: diff --git a/plugins/example-code-snippets/src/examples/resolvers/source-parsers/languages/dart-snippet-source-parser.ts b/plugins/example-code-snippets/src/examples/resolvers/source-parsers/languages/dart-snippet-source-parser.ts index e4ec99bfb7..ef0047fc83 100644 --- a/plugins/example-code-snippets/src/examples/resolvers/source-parsers/languages/dart-snippet-source-parser.ts +++ b/plugins/example-code-snippets/src/examples/resolvers/source-parsers/languages/dart-snippet-source-parser.ts @@ -9,7 +9,7 @@ export class DartSnippetSourceParser extends RegexSnippetSourceParser { constructor(repoSourceDir: string) { const wholeFileExamplesDir = 'example/'; const codeSnippetFiles: Array = [ - 'example/doc_example_apis/doc_example_apis.dart', + 'example/doc_example_apis/bin/doc_example_apis.dart', ]; super({ wholeFileExamplesDir: path.join(repoSourceDir, wholeFileExamplesDir), diff --git a/plugins/example-code-snippets/src/examples/resolvers/source-parsers/languages/kotlin-snippet-source-parser.ts b/plugins/example-code-snippets/src/examples/resolvers/source-parsers/languages/kotlin-snippet-source-parser.ts new file mode 100644 index 0000000000..e6bbbce307 --- /dev/null +++ b/plugins/example-code-snippets/src/examples/resolvers/source-parsers/languages/kotlin-snippet-source-parser.ts @@ -0,0 +1,36 @@ +import { + RegexSnippetSourceParser, + RegexSnippetTypeOptions, +} from '../regex-snippet-source-parser'; +import {ExampleSnippetType} from '../../../examples'; +import * as path from 'path'; + +export class KotlinSnippetSourceParser extends RegexSnippetSourceParser { + constructor(repoSourceDir: string) { + const wholeFileExamplesDir = + 'examples/src/main/kotlin/software/momento/example/doc_examples'; + const codeSnippetFiles: Array = [ + 'examples/src/main/kotlin/software/momento/example/doc_examples/DocExamples.kt', + ]; + super({ + wholeFileExamplesDir: path.join(repoSourceDir, wholeFileExamplesDir), + snippetTypeParseOptions: new Map< + ExampleSnippetType, + RegexSnippetTypeOptions + >([ + [ + ExampleSnippetType.CODE, + { + snippetSourceFiles: codeSnippetFiles.map(f => + path.join(repoSourceDir, f) + ), + startRegex: snippetId => + new RegExp(`^suspend fun example_${snippetId.valueOf()}\\(`), + endRegex: () => /^}/, + numLeadingSpacesToStrip: 4, + }, + ], + ]), + }); + } +} diff --git a/plugins/example-code-snippets/src/examples/sdk-source/sdk-github-repo-source-provider.ts b/plugins/example-code-snippets/src/examples/sdk-source/sdk-github-repo-source-provider.ts index 238df01cde..956e9f5e08 100644 --- a/plugins/example-code-snippets/src/examples/sdk-source/sdk-github-repo-source-provider.ts +++ b/plugins/example-code-snippets/src/examples/sdk-source/sdk-github-repo-source-provider.ts @@ -25,6 +25,8 @@ export function githubRepoNameForSdk(sdk: Sdk): string { return 'client-sdk-go'; case Sdk.JAVA: return 'client-sdk-java'; + case Sdk.KOTLIN: + return 'client-sdk-kotlin'; case Sdk.PHP: return 'client-sdk-php'; case Sdk.RUST: diff --git a/plugins/example-code-snippets/src/examples/sdk-source/sdks.ts b/plugins/example-code-snippets/src/examples/sdk-source/sdks.ts index 81c4d69519..461f81d1cc 100644 --- a/plugins/example-code-snippets/src/examples/sdk-source/sdks.ts +++ b/plugins/example-code-snippets/src/examples/sdk-source/sdks.ts @@ -8,6 +8,7 @@ export enum Sdk { PYTHON = 'python', GO = 'go', JAVA = 'java', + KOTLIN = 'kotlin', PHP = 'php', RUST = 'rust', RUBY = 'ruby', @@ -31,6 +32,8 @@ export function sdkDisplayName(sdk: Sdk): string { return 'Go'; case Sdk.JAVA: return 'Java'; + case Sdk.KOTLIN: + return 'Kotlin'; case Sdk.PHP: return 'PHP'; case Sdk.RUST: diff --git a/plugins/example-code-snippets/src/inject-example-code-snippets.ts b/plugins/example-code-snippets/src/inject-example-code-snippets.ts index e56988b2c5..776fc64464 100644 --- a/plugins/example-code-snippets/src/inject-example-code-snippets.ts +++ b/plugins/example-code-snippets/src/inject-example-code-snippets.ts @@ -68,6 +68,7 @@ function replaceValueWithExampleTabs(literal: unist.Literal): void { js={\`${snippetForLanguage(ExampleLanguage.JAVASCRIPT, snippetId)}\`} python={\`${snippetForLanguage(ExampleLanguage.PYTHON, snippetId)}\`} java={\`${snippetForLanguage(ExampleLanguage.JAVA, snippetId)}\`} + kotlin={\`${snippetForLanguage(ExampleLanguage.KOTLIN, snippetId)}\`} go={\`${snippetForLanguage(ExampleLanguage.GO, snippetId)}\`} csharp={\`${snippetForLanguage(ExampleLanguage.CSHARP, snippetId)}\`} php={\`${snippetForLanguage(ExampleLanguage.PHP, snippetId)}\`} @@ -87,6 +88,7 @@ function replaceValueWithExampleFileTabs(literal: unist.Literal): void { js={\`${fileTabContentsForLanguage(value, ExampleLanguage.JAVASCRIPT)}\`} python={\`${fileTabContentsForLanguage(value, ExampleLanguage.PYTHON)}\`} java={\`${fileTabContentsForLanguage(value, ExampleLanguage.JAVA)}\`} + kotlin={\`${fileTabContentsForLanguage(value, ExampleLanguage.KOTLIN)}\`} go={\`${fileTabContentsForLanguage(value, ExampleLanguage.GO)}\`} csharp={\`${fileTabContentsForLanguage(value, ExampleLanguage.CSHARP)}\`} php={\`${fileTabContentsForLanguage(value, ExampleLanguage.PHP)}\`} diff --git a/src/components/SdkExampleFileTabs/index.jsx b/src/components/SdkExampleFileTabs/index.jsx index 9893338793..8053719fe1 100644 --- a/src/components/SdkExampleFileTabs/index.jsx +++ b/src/components/SdkExampleFileTabs/index.jsx @@ -11,6 +11,6 @@ import React from 'react'; * @param snippetId: string * @constructor */ -export const SdkExampleFileTabs = ({javascript, python, java, go, csharp, php, rust, ruby, elixir, swift, dart, cli}) => {}; +export const SdkExampleFileTabs = ({javascript, python, java, kotlin, go, csharp, php, rust, ruby, elixir, swift, dart, cli}) => {}; diff --git a/src/components/SdkExampleFileTabsImpl/index.jsx b/src/components/SdkExampleFileTabsImpl/index.jsx index 4e5ee789b3..544e5f9ea2 100644 --- a/src/components/SdkExampleFileTabsImpl/index.jsx +++ b/src/components/SdkExampleFileTabsImpl/index.jsx @@ -13,6 +13,7 @@ import React from 'react'; * @param js * @param python * @param java + * @param kotlin * @param go * @param csharp * @param php @@ -25,8 +26,8 @@ import React from 'react'; * @returns {JSX.Element|null} * @constructor */ -export const SdkExampleFileTabsImpl = ({js, python, java, go, csharp, php, rust, ruby, elixir, swift, dart, cli}) => { - if (js || python || java || go || csharp || php || rust || ruby || elixir || swift || dart || cli) { +export const SdkExampleFileTabsImpl = ({js, python, java, kotlin, go, csharp, php, rust, ruby, elixir, swift, dart, cli}) => { + if (js || python || java || kotlin || go || csharp || php || rust || ruby || elixir || swift || dart || cli) { return ( {js && @@ -41,6 +42,10 @@ export const SdkExampleFileTabsImpl = ({js, python, java, go, csharp, php, rust, {java} } + {kotlin && + + {kotlin} + } {go && {go} diff --git a/src/components/SdkExampleTabsImpl/index.jsx b/src/components/SdkExampleTabsImpl/index.jsx index 7039248d1c..fe395279fa 100644 --- a/src/components/SdkExampleTabsImpl/index.jsx +++ b/src/components/SdkExampleTabsImpl/index.jsx @@ -13,6 +13,7 @@ import React from 'react'; * @param js * @param python * @param java + * @param kotlin * @param go * @param csharp * @param php @@ -25,8 +26,8 @@ import React from 'react'; * @returns {JSX.Element|null} * @constructor */ -export const SdkExampleTabsImpl = ({js, python, java, go, csharp, php, rust, ruby, elixir, swift, dart, cli}) => { - if (js || python || java || go || csharp || php || rust || ruby || elixir || swift || dart || cli) { +export const SdkExampleTabsImpl = ({js, python, java, kotlin, go, csharp, php, rust, ruby, elixir, swift, dart, cli}) => { + if (js || python || java || kotlin || go || csharp || php || rust || ruby || elixir || swift || dart || cli) { return ( {js && @@ -41,6 +42,10 @@ export const SdkExampleTabsImpl = ({js, python, java, go, csharp, php, rust, rub {java} } + {kotlin && + + {kotlin} + } {go && {go}