From 00880b2e1ac23854c22f42445e1123ab88c7e193 Mon Sep 17 00:00:00 2001 From: momo-jun Date: Thu, 27 Apr 2023 10:04:02 +0800 Subject: [PATCH 1/5] Update sidebars.json --- sidebars.json | 61 ++++++++++++++++++++++----------------------------- 1 file changed, 26 insertions(+), 35 deletions(-) diff --git a/sidebars.json b/sidebars.json index 4f539bdd3ae7..1e9991ca8b20 100644 --- a/sidebars.json +++ b/sidebars.json @@ -39,11 +39,7 @@ { "type": "category", "label": "Pulsar Schema", - "items": [ - "schema-overview", - "schema-understand", - "schema-get-started" - ] + "items": ["schema-overview", "schema-understand", "schema-get-started"] }, { "type": "category", @@ -201,14 +197,7 @@ { "type": "category", "label": "Transactions", - "items": [ - "txn-why", - "txn-what", - "txn-use", - "txn-advanced-features", - "txn-monitor", - "txn-how" - ] + "items": ["txn-why", "txn-what", "txn-how", "txn-use", "txn-monitor"] }, { "type": "category", @@ -219,7 +208,7 @@ }, "items": [ "deploy-aws", - "deploy-ibm", + "deploy-ibm", { "type": "category", "label": "Kubernetes", @@ -227,11 +216,7 @@ "type": "doc", "id": "deploy-kubernetes" }, - "items": [ - "helm-prepare", - "helm-deploy", - "helm-upgrade" - ] + "items": ["helm-prepare", "helm-deploy", "helm-upgrade"] }, "deploy-bare-metal", "deploy-bare-metal-multi-cluster", @@ -268,9 +253,9 @@ "type": "category", "label": "Observability", "items": [ - "administration-stats", - "reference-metrics", - "deploy-monitoring" + "administration-stats", + "reference-metrics", + "deploy-monitoring" ] }, { @@ -306,15 +291,18 @@ { "type": "category", "label": "Performance", - "items": [ - "performance-pulsar-perf" - ] + "items": ["performance-pulsar-perf"] }, { "type": "category", "label": "Client Libraries", "items": [ "client-libraries", + { + "type": "link", + "href": "/client-feature-matrix/", + "label": "Client Feature Matrix" + }, { "type": "category", "label": "Get started", @@ -381,8 +369,7 @@ "items": [ "client-libraries-node-setup", "client-libraries-node-initialize", - "client-libraries-node-use", - "client-libraries-node-configs" + "client-libraries-node-use" ] }, { @@ -417,6 +404,16 @@ } ] }, + { + "type": "category", + "label": "Pulsar API", + "items": ["pulsar-api-overview"] + }, + { + "type": "category", + "label": "Client API", + "items": ["client-api-overview"] + }, { "type": "category", "label": "Admin API", @@ -451,11 +448,7 @@ { "type": "category", "label": "Adaptors", - "items": [ - "adaptors-kafka", - "adaptors-spark", - "adaptors-storm" - ] + "items": ["adaptors-kafka", "adaptors-spark", "adaptors-storm"] }, { "type": "category", @@ -506,9 +499,7 @@ "type": "doc", "id": "pulsar-api-overview" }, - "items": [ - "reference-rest-api-overview" - ] + "items": ["reference-rest-api-overview"] }, "reference-terminology", "reference-cli-tools", From 41ffbfa56a461f09b7c6b43ae8570eb3a2847aa6 Mon Sep 17 00:00:00 2001 From: momo-jun Date: Fri, 28 Apr 2023 13:40:24 +0800 Subject: [PATCH 2/5] add the new client feature matrix into the navigation and update reference links --- docs/client-libraries-cpp.md | 4 ++-- docs/client-libraries-dotnet.md | 4 ++-- docs/client-libraries-go.md | 4 ++-- docs/client-libraries-java.md | 4 ++-- docs/client-libraries-node.md | 4 ++-- docs/client-libraries-python.md | 4 ++-- docs/client-libraries-websocket.md | 2 +- docs/client-libraries.md | 2 +- sidebars.json | 10 ---------- 9 files changed, 14 insertions(+), 24 deletions(-) diff --git a/docs/client-libraries-cpp.md b/docs/client-libraries-cpp.md index 7f583f235c4e..49a6d31fdd38 100644 --- a/docs/client-libraries-cpp.md +++ b/docs/client-libraries-cpp.md @@ -26,10 +26,10 @@ You can use a Pulsar C++ client to create Pulsar [producers](concepts-clients.md - [Producer configurations](@pulsar:apidoc:cpp@/classpulsar_1_1_producer_configuration.html) - [Consumer configurations](@pulsar:apidoc:cpp@/classpulsar_1_1_consumer_configuration.html) - [Reader configurations](@pulsar:apidoc:cpp@/classpulsar_1_1_reader_configuration.html) -- [Release notes](pathname:///release-notes/client-cpp) +- [Release notes](/release-notes/client-cpp) - [Code examples](https://github.com/apache/pulsar-client-cpp/tree/main/examples) - [Supported schema types](https://github.com/apache/pulsar-client-cpp/blob/main/include/pulsar/Schema.h) -- [Client feature matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) +- [Client feature matrix](/client-feature-matrix/) ## Changes for 3.0.0 and later versions diff --git a/docs/client-libraries-dotnet.md b/docs/client-libraries-dotnet.md index f6e8bb367516..557920f7ad86 100644 --- a/docs/client-libraries-dotnet.md +++ b/docs/client-libraries-dotnet.md @@ -21,6 +21,6 @@ You can use the Pulsar C# client (DotPulsar) to create Pulsar [producers](concep ## Reference doc -- [Release notes](pathname:///release-notes/client-cs) +- [Release notes](/release-notes/client-cs) - [DotPulsar documentation](https://github.com/apache/pulsar-dotpulsar/wiki) -- [Client feature matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) \ No newline at end of file +- [Client feature matrix](/client-feature-matrix/) \ No newline at end of file diff --git a/docs/client-libraries-go.md b/docs/client-libraries-go.md index 802c88a2377e..3481affe55cd 100644 --- a/docs/client-libraries-go.md +++ b/docs/client-libraries-go.md @@ -26,5 +26,5 @@ You can use a Pulsar [Go client](https://github.com/apache/pulsar-client-go) to - [Producer configurations](https://pkg.go.dev/github.com/apache/pulsar-client-go/pulsar#ProducerOptions) - [Consumer configurations](https://pkg.go.dev/github.com/apache/pulsar-client-go/pulsar#ConsumerOptions) - [Reader configurations](https://pkg.go.dev/github.com/apache/pulsar-client-go/pulsar#ReaderOptions) -- [Release notes](pathname:///release-notes/client-go) -- [Client feature matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) \ No newline at end of file +- [Release notes](/release-notes/client-go) +- [Client feature matrix](/client-feature-matrix/) \ No newline at end of file diff --git a/docs/client-libraries-java.md b/docs/client-libraries-java.md index 549e018f1bd6..f536f5273b10 100644 --- a/docs/client-libraries-java.md +++ b/docs/client-libraries-java.md @@ -36,5 +36,5 @@ Package | Description | Maven Artifact #### More reference - [Java client configurations](pathname:///reference/#/@pulsar:version_reference@/client/) -- [Release notes](pathname:///release-notes/client-java) -- [Client feature matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) \ No newline at end of file +- [Release notes](/release-notes/client-java) +- [Client feature matrix](/client-feature-matrix/) \ No newline at end of file diff --git a/docs/client-libraries-node.md b/docs/client-libraries-node.md index 923ae85a639e..878dffae724d 100644 --- a/docs/client-libraries-node.md +++ b/docs/client-libraries-node.md @@ -22,6 +22,6 @@ You can use a Pulsar Node.js client to create Pulsar [producers](concepts-client ## Reference doc - [Node.js client configurations](client-libraries-node-configs.md) -- [Release notes](pathname://release-notes/client-node/) -- [Client feature matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) +- [Release notes](/release-notes/client-node) +- [Client feature matrix](/client-feature-matrix/) - [Type definitions](https://github.com/apache/pulsar-client-node/blob/master/index.d.ts) used in TypeScript (for 1.3.0 or later versions). \ No newline at end of file diff --git a/docs/client-libraries-python.md b/docs/client-libraries-python.md index 4fc639e48d1b..a79be4b14661 100644 --- a/docs/client-libraries-python.md +++ b/docs/client-libraries-python.md @@ -26,5 +26,5 @@ You can use a Pulsar Python client to create Pulsar [producers](concepts-clients - [Producer configurations](@pulsar:apidoc:python@/pulsar.Client.html#create_producer) - [Consumer configurations](@pulsar:apidoc:python@/pulsar.Client.html#subscribe) - [Reader configurations](@pulsar:apidoc:python@/pulsar.Client.html#create_reader) -- [Release notes](pathname:///release-notes/client-python) -- [Client feature matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) \ No newline at end of file +- [Release notes](//release-notes/client-python) +- [Client feature matrix](/client-feature-matrix/) \ No newline at end of file diff --git a/docs/client-libraries-websocket.md b/docs/client-libraries-websocket.md index 937cdec920c7..f02da082099f 100644 --- a/docs/client-libraries-websocket.md +++ b/docs/client-libraries-websocket.md @@ -6,7 +6,7 @@ sidebar_label: "WebSocket" Pulsar [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API provides a simple way to interact with Pulsar using languages that do not have an official [client library](client-libraries.md). You can use Pulsar WebSocket API with any WebSocket client library. See [Python and Node.js examples](#client-examples) for more details. -Through WebSocket, you can publish and consume messages and use features available on the [Client Feature Matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) page. +Through WebSocket, you can publish and consume messages and use features available on the [Client Feature Matrix](/client-feature-matrix/) page. ## Run the WebSocket service diff --git a/docs/client-libraries.md b/docs/client-libraries.md index 13dcab809f0b..5e58164adabf 100644 --- a/docs/client-libraries.md +++ b/docs/client-libraries.md @@ -34,7 +34,7 @@ Pulsar supports the following language-agnostic client libraries: ## Feature matrix -Pulsar client feature matrix for different languages is listed on [Pulsar Feature Matrix (Client and Function)](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) page. +The [Client Feature Matrix](/client-feature-matrix/) page provides an overview of the latest feature supportability on language-specific clients. ## Third-party clients diff --git a/sidebars.json b/sidebars.json index 1e9991ca8b20..04852f41a29d 100644 --- a/sidebars.json +++ b/sidebars.json @@ -404,16 +404,6 @@ } ] }, - { - "type": "category", - "label": "Pulsar API", - "items": ["pulsar-api-overview"] - }, - { - "type": "category", - "label": "Client API", - "items": ["client-api-overview"] - }, { "type": "category", "label": "Admin API", From eab5f5301ad7c1f7c118e5aa9aa239fe35bd2fec Mon Sep 17 00:00:00 2001 From: momo-jun Date: Fri, 28 Apr 2023 14:09:18 +0800 Subject: [PATCH 3/5] Update sidebars.json --- sidebars.json | 44 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/sidebars.json b/sidebars.json index 04852f41a29d..de1353c7a88d 100644 --- a/sidebars.json +++ b/sidebars.json @@ -39,7 +39,11 @@ { "type": "category", "label": "Pulsar Schema", - "items": ["schema-overview", "schema-understand", "schema-get-started"] + "items": [ + "schema-overview", + "schema-understand", + "schema-get-started" + ] }, { "type": "category", @@ -197,7 +201,14 @@ { "type": "category", "label": "Transactions", - "items": ["txn-why", "txn-what", "txn-how", "txn-use", "txn-monitor"] + "items": [ + "txn-why", + "txn-what", + "txn-use", + "txn-advanced-features", + "txn-monitor", + "txn-how" + ] }, { "type": "category", @@ -216,7 +227,11 @@ "type": "doc", "id": "deploy-kubernetes" }, - "items": ["helm-prepare", "helm-deploy", "helm-upgrade"] + "items": [ + "helm-prepare", + "helm-deploy", + "helm-upgrade" + ] }, "deploy-bare-metal", "deploy-bare-metal-multi-cluster", @@ -253,9 +268,9 @@ "type": "category", "label": "Observability", "items": [ - "administration-stats", - "reference-metrics", - "deploy-monitoring" + "administration-stats", + "reference-metrics", + "deploy-monitoring" ] }, { @@ -291,7 +306,9 @@ { "type": "category", "label": "Performance", - "items": ["performance-pulsar-perf"] + "items": [ + "performance-pulsar-perf" + ] }, { "type": "category", @@ -369,7 +386,8 @@ "items": [ "client-libraries-node-setup", "client-libraries-node-initialize", - "client-libraries-node-use" + "client-libraries-node-use", + "client-libraries-node-configs" ] }, { @@ -438,7 +456,11 @@ { "type": "category", "label": "Adaptors", - "items": ["adaptors-kafka", "adaptors-spark", "adaptors-storm"] + "items": [ + "adaptors-kafka", + "adaptors-spark", + "adaptors-storm" + ] }, { "type": "category", @@ -489,7 +511,9 @@ "type": "doc", "id": "pulsar-api-overview" }, - "items": ["reference-rest-api-overview"] + "items": [ + "reference-rest-api-overview" + ] }, "reference-terminology", "reference-cli-tools", From 65c709ad38641b8c5f69b186bf2c235233a887fc Mon Sep 17 00:00:00 2001 From: momo-jun Date: Thu, 4 May 2023 18:06:43 +0800 Subject: [PATCH 4/5] Update the contribution guide --- contribute/document-contribution.md | 24 +++++++++++++----------- contribute/site-intro.md | 26 +++++++++++++++----------- 2 files changed, 28 insertions(+), 22 deletions(-) diff --git a/contribute/document-contribution.md b/contribute/document-contribution.md index f99d410b0f06..cbe5d84fe22f 100644 --- a/contribute/document-contribution.md +++ b/contribute/document-contribution.md @@ -77,21 +77,23 @@ Docs for external command-line tools or bare scripts are updated **manually**: | pulsar-daemon | [pulsar-daemon.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/pulsar-daemon/pulsar-daemon.md) | | bookkeeper | [bookkeeper.md](https://github.com/apache/pulsar-site/blob/main/static/reference/next/bookkeeper/bookkeeper.md) | -## Update client/function matrix +## Update feature matrix -[Pulsar Feature Matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914) outlines every feature supported by the Pulsar client and function. +Pulsar feature matrix introduces the features supported by language-specific clients and functions. It includes: +* [Client Feature Matrix](pathname:///client-feature-matrix) +* [Function Feature Matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=328808194) -:::note +You need to update the feature matrix as soon as your related commits get merged. The workflow is illustrated as follows. -* It's public and everyone has access to edit it. You can reach out to `dev@pulsar.apache.org` if you have problems in editing. -* This matrix will be moved to the Pulsar website (instead of the spreadsheet) in the future. +![Client Feature Matrix Workflow](media/client-matrix-workflow.png) -::: +1. Submit your code and doc PRs. +2. Get your PRs reviewed and merged. +3. Update the feature matrix to flag your contribution. -If you want to update the Pulsar Feature Matrix, follow the steps below. +:::note -1. Submit your code and doc PRs. -2. Get your PR reviewed and merged. -3. In the [Pulsar Feature Matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=1784579914), check the box in the corresponding cell with the links of PRs and doc site. +* [Client Feature Matrix](pathname:///client-feature-matrix) is in the transition phase from the spreadsheet to the webpage. For how to update it, see [How to update data-driven pages](site-intro.md#how-to-update-data-driven-pages). +* If you have problems in editing the spreadsheet of [Function Feature Matrix](https://docs.google.com/spreadsheets/d/1YHYTkIXR8-Ql103u-IMI18TXLlGStK8uJjDsOOA0T20/edit#gid=328808194), you can reach out to `dev@pulsar.apache.org`. -![Client Feature Matrix Workflow](media/client-matrix-workflow.png) +::: \ No newline at end of file diff --git a/contribute/site-intro.md b/contribute/site-intro.md index 7c1a3db22703..3e5567626a74 100644 --- a/contribute/site-intro.md +++ b/contribute/site-intro.md @@ -1,6 +1,6 @@ # Introduction -The Pulsar site is built with [Docusaurus](http://docusaurus.io/) framework. You can find all technical details on [its docs](https://docusaurus.io/docs). +The Pulsar site is built with [Docusaurus](http://docusaurus.io/) framework. You can find all the technical details on [its docs](https://docusaurus.io/docs). Specifically, this chapter provides a [writing syntax](document-syntax.md) guide selecting knowledge for writing content of the site. @@ -14,14 +14,15 @@ Docusaurus provides three kinds of pages out-of-the-box: [docs](https://docusaur The Pulsar site pages are of: -| Page | Type | Source | -|--------------------------------------------|-----------|---------------------------------------------------------------------------------------------------| -| [User docs](pathname:///docs) | docs |
  • docs/
  • versioned_docs/
  • versioned_sidebars/
  • sidebars.json
| -| [Contribution guides](about.md) | docs |
  • contribute/
  • sidebarsDevelopment.js
| -| [Release notes](pathname:///release-notes) | docs |
  • release-notes/
  • sidebarsReleaseNotes.js
| -| [Security](pathname:///security) | docs |
  • security/
| -| [Blogs](pathname:///blog) | blog |
  • blog/
| -| Other pages | JSX pages |
  • src/pages/
| +| Page | Type | Source | +|------------------------------------------------------------|-----------|---------------------------------------------------------------------------------------------------| +| [User docs](pathname:///docs) | docs |
  • docs/
  • versioned_docs/
  • versioned_sidebars/
  • sidebars.json
| +| [Contribution guides](about.md) | docs |
  • contribute/
  • sidebarsDevelopment.js
| +| [Release notes](pathname:///release-notes) | docs |
  • release-notes/
  • sidebarsReleaseNotes.js
| +| [Security](pathname:///security) | docs |
  • security/
| +| [Blogs](pathname:///blog) | blog |
  • blog/
| +| [Client feature matrix](pathname:///client-feature-matrix) | docs |
  • client-feature-matrix/
  • data/matrix.js
| +| Other pages | JSX pages |
  • src/pages/
| Besides, the site serves multiple static pages generated outside the framework, including API docs, reference docs, and swagger files. You can find them under the `static` folder. @@ -39,7 +40,7 @@ See the [previewing content](document-preview.md) guide for more details. ### docker-compose.yaml -The `preview.sh` script use the Docusaurus dev server for testing, which is different from the real Apache Web Server based env that serves the site online. +The `preview.sh` script uses the Docusaurus dev server for testing, which is different from the real Apache Web Server based env that serves the site online. To emulate the server-side logics, like `.htaccess` rewrite rules, you can run: @@ -74,7 +75,7 @@ If you're gonna to update the content, read the [update reference docs](document If you're gonna to debug the reference generation process, read the [reference-doc-generator](https://github.com/apache/pulsar-site/tree/main/tools/pytools#reference-doc-generator) usage section and its source code. -### How to update data driven pages? +### How to update data-driven pages? The following pages contain data-driven tables: @@ -106,5 +107,8 @@ The following pages contain data-driven tables: * [Team](pathname:///team) * data/team.js * src/pages/team.js +* [Client feature matrix](pathname:///client-feature-matrix) + * data/matrix.js + * client-feature-matrix/index.mdx Additionally, PMC members can generate the `team.js` file as @lhotari did in https://github.com/apache/pulsar-site/pull/387. From 5e0ebab2f819c0cf77a3e4d058754624c6ebedae Mon Sep 17 00:00:00 2001 From: momo-jun Date: Thu, 4 May 2023 18:10:08 +0800 Subject: [PATCH 5/5] fix --- docs/client-libraries-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/client-libraries-python.md b/docs/client-libraries-python.md index a79be4b14661..70114ab8fe32 100644 --- a/docs/client-libraries-python.md +++ b/docs/client-libraries-python.md @@ -26,5 +26,5 @@ You can use a Pulsar Python client to create Pulsar [producers](concepts-clients - [Producer configurations](@pulsar:apidoc:python@/pulsar.Client.html#create_producer) - [Consumer configurations](@pulsar:apidoc:python@/pulsar.Client.html#subscribe) - [Reader configurations](@pulsar:apidoc:python@/pulsar.Client.html#create_reader) -- [Release notes](//release-notes/client-python) +- [Release notes](/release-notes/client-python) - [Client feature matrix](/client-feature-matrix/) \ No newline at end of file