You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2021/06/29 08:48:28 UTC
[GitHub] [pulsar] Anonymitaet opened a new pull request #11146: [Doc] Add descriptions for various API docs
Anonymitaet opened a new pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146
Fix issues discussed in https://github.com/apache/pulsar/pull/11106
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870418149
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870418149
@gmethvin @BewareMyPower could you please help review? Thanks
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] gmethvin commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
gmethvin commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660430236
##########
File path: site2/docs/admin-api-namespaces.md
##########
@@ -905,7 +915,7 @@ admin.namespaces().removeDeduplicationSnapshotInterval(namespace)
### Namespace isolation
-Coming soon.
+You can use the Pulsar isolation policy to allocate resources (broker and bookie) for a namespace. For more information, see [here](administration-isolation.md).
Review comment:
I'd just linkify the term "Pulsar isolation policy" and remove the entire second sentence.
##########
File path: site2/docs/admin-api-overview.md
##########
@@ -9,15 +9,26 @@ The Pulsar admin interface enables you to manage all important entities in a Pul
You can interact with the admin interface via:
- HTTP calls, which are made against the admin {@inject: rest:REST:/} API provided by Pulsar brokers. For some RESTful APIs, they might be redirected to the owner brokers for serving with [`307 Temporary Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307), hence the HTTP callers should handle `307 Temporary Redirect`. If you use `curl` commands, you should specify `-L` to handle redirections.
+
+ > **Tip**
Review comment:
Why is this a "tip" and on the other page it's "important"?
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](http://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
Review comment:
nit: no need for backticks here and on the below line, since we're not referring to a command. It can simply be "the REST API" and "the Java admin API".
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] gmethvin commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
gmethvin commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660896244
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](http://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
Review comment:
Typically you'd use *italic* or **bold** text for emphasis. Anyway you're still missing the article _the_ in front of "REST API" and "admin API"
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] tuteng edited a comment on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
tuteng edited a comment on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870446087
> I have another question that may not block the merge this PR.
>
> 
>
> Why are there only documents of SNAPSHOT versions? Do you know the reason? @tuteng
I think it is related to the https://github.com/apache/pulsar/blob/master/pom.xml#L35 configuration of the pom, It gets the version information through this script https://github.com/apache/pulsar/blob/master/site2/tools/pulsar-admin-doc-gen.sh#L22 @BewareMyPower
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660470423
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](http://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
Review comment:
Since I want to emphasize the keyword (pulsar-admin, rest API, java admin api), so I use a special format (backticks).
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](http://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
Review comment:
Since I want to emphasize the keyword (pulsar-admin, rest API, java admin API), so I use a special format (backticks).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] gmethvin commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
gmethvin commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870850833
@Anonymitaet I actually was thinking you could use an include so it appears in the same page but can be split out into another file. Docusaurus apparently has a plugin to support includes: https://www.npmjs.com/package/docusaurus-plugin-includes
I think it's ok as-is, but I figured it might be worth it given how much duplicated text there is.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-871039369
> @Anonymitaet I actually was thinking you could use an include so it appears in the same page but can be split out into another file. Docusaurus apparently has a plugin to support includes: https://www.npmjs.com/package/docusaurus-plugin-includes
>
> I think it's ok as-is, but I figured it might be worth it given how much duplicated text there is.
Hi @gmethvin thanks for sharing this great thought. However, I do not have an idea on the "`include` (I search `docusaurus plugin`but got only one result), can you explain a bit more? can you give a sample or example of that?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660470423
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](http://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
Review comment:
Since I want to emphasize the keyword (pulsar-admin, rest API, java admin api), so I use a special format (backticks).
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](http://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
Review comment:
Since I want to emphasize the keyword (pulsar-admin, rest API, java admin API), so I use a special format (backticks).
##########
File path: site2/docs/admin-api-namespaces.md
##########
@@ -905,7 +915,7 @@ admin.namespaces().removeDeduplicationSnapshotInterval(namespace)
### Namespace isolation
-Coming soon.
+You can use the Pulsar isolation policy to allocate resources (broker and bookie) for a namespace. For more information, see [here](administration-isolation.md).
Review comment:
OK. Done.
##########
File path: site2/docs/admin-api-overview.md
##########
@@ -9,15 +9,26 @@ The Pulsar admin interface enables you to manage all important entities in a Pul
You can interact with the admin interface via:
- HTTP calls, which are made against the admin {@inject: rest:REST:/} API provided by Pulsar brokers. For some RESTful APIs, they might be redirected to the owner brokers for serving with [`307 Temporary Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307), hence the HTTP callers should handle `307 Temporary Redirect`. If you use `curl` commands, you should specify `-L` to handle redirections.
+
+ > **Tip**
Review comment:
Updated these "tips" to "important" for keeping consistent.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] BewareMyPower commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
BewareMyPower commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870429434
I have another question that may not block the merge this PR.
Why are there only documents of SNAPSHOT versions? Do you know the reason? @tuteng
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] tuteng commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
tuteng commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870446087
> I have another question that may not block the merge this PR.
>
> 
>
> Why are there only documents of SNAPSHOT versions? Do you know the reason? @tuteng
I think it is related to the https://github.com/apache/pulsar/blob/master/pom.xml#L35 configuration of the pom @BewareMyPower
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] gmethvin commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
gmethvin commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660902805
##########
File path: site2/docs/admin-api-clusters.md
##########
@@ -4,14 +4,24 @@ title: Managing Clusters
sidebar_label: Clusters
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
Review comment:
I'm actually not sure what we want to call this page, but it would be useful to have a clear name. Should we just call it the "documentation"? or maybe it's a "manual"? I kind of like the term manual since it's essentially a man page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] gmethvin commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
gmethvin commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660901858
##########
File path: site2/docs/admin-api-clusters.md
##########
@@ -4,14 +4,24 @@ title: Managing Clusters
sidebar_label: Clusters
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
Review comment:
Using a link with only the text "here" or "click here" is generally not good for UX. An alternative would be something like:
> For the latest and most complete information about `pulsar-admin`, see [the pulsar-admin documentation](https://pulsar.apache.org/tools/pulsar-admin/)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870483161
> Is it possible to split out the redundant text into another file and include it in all the relevant files? It's not a huge deal but it'd be nice if we didn't have to manually keep all those pages in sync.
@gmethvin thanks for your suggestions, this is a good idea. However, after thinking twice, I still want to keep the important notice on each of the following pages, reason:
Suppose that we create an independent page containing the important notice and add the link of the independent page to each of the following pages, then users need to get the info with more clicks and links, which is not a friendly experience. Instead of providing more links to users, it would be better to guide them directly and efficiently.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet merged pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet merged pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Jennifer88huang commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660999687
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
Review comment:
Do we need to add the same note everywhere in the docs? If it's general note that users need to pay attention to, it's better to highlight it in a central place, e.g.: overview.
We do not need to replace the same content again and again in all docs.
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
+>
+> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [here](https://pulsar.apache.org/api/admin/).
+
Pulsar brokers consist of two components:
1. An HTTP server exposing a {@inject: rest:REST:/} interface administration and [topic](reference-terminology.md#topic) lookup.
2. A dispatcher that handles all Pulsar [message](reference-terminology.md#message) transfers.
[Brokers](reference-terminology.md#broker) can be managed via:
-* The [`brokers`](reference-pulsar-admin.md#brokers) command of the [`pulsar-admin`](reference-pulsar-admin.md) tool
+* The `brokers` command of the [`pulsar-admin`](https://pulsar.apache.org/tools/pulsar-admin/) tool
Review comment:
Thank you for fixing the links one by one.
In the future, we can add link for the first time it appears, and do not add links for other occurances.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet edited a comment on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet edited a comment on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870418149
@gmethvin could you please help review? Thanks
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] gmethvin commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
gmethvin commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660430236
##########
File path: site2/docs/admin-api-namespaces.md
##########
@@ -905,7 +915,7 @@ admin.namespaces().removeDeduplicationSnapshotInterval(namespace)
### Namespace isolation
-Coming soon.
+You can use the Pulsar isolation policy to allocate resources (broker and bookie) for a namespace. For more information, see [here](administration-isolation.md).
Review comment:
I'd just linkify the term "Pulsar isolation policy" and remove the entire second sentence.
##########
File path: site2/docs/admin-api-overview.md
##########
@@ -9,15 +9,26 @@ The Pulsar admin interface enables you to manage all important entities in a Pul
You can interact with the admin interface via:
- HTTP calls, which are made against the admin {@inject: rest:REST:/} API provided by Pulsar brokers. For some RESTful APIs, they might be redirected to the owner brokers for serving with [`307 Temporary Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307), hence the HTTP callers should handle `307 Temporary Redirect`. If you use `curl` commands, you should specify `-L` to handle redirections.
+
+ > **Tip**
Review comment:
Why is this a "tip" and on the other page it's "important"?
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](http://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
Review comment:
nit: no need for backticks here and on the below line, since we're not referring to a command. It can simply be "the REST API" and "the Java admin API".
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r661069058
##########
File path: site2/docs/admin-api-clusters.md
##########
@@ -4,14 +4,24 @@ title: Managing Clusters
sidebar_label: Clusters
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
Review comment:
Hi @gmethvin, thanks for your suggestion. I've updated them to `xxx, see [pulsar-admin doc](xxx) / see [REST API doc](xxx) / see [Java admin API doc](xxx)`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Jennifer88huang commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660999687
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
Review comment:
Do we need to add the same note everywhere in the docs? If it's general note that users need to pay attention to, it's better to highlight it in a central place, e.g.: overview.
We do not need to place the same content again and again in all docs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet edited a comment on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet edited a comment on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870418149
@gmethvin could you please help review? Thanks
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] tuteng commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
tuteng commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870446087
> I have another question that may not block the merge this PR.
>
> 
>
> Why are there only documents of SNAPSHOT versions? Do you know the reason? @tuteng
I think it is related to the https://github.com/apache/pulsar/blob/master/pom.xml#L35 configuration of the pom @BewareMyPower
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r661069058
##########
File path: site2/docs/admin-api-clusters.md
##########
@@ -4,14 +4,24 @@ title: Managing Clusters
sidebar_label: Clusters
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
Review comment:
Hi @gmethvin, thanks for your suggestion. I've updated them to "xxx, see [pulsar-admin doc](xxx) / see [REST API doc](xxx) / see [Java admin API doc](xxx).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Jennifer88huang commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r661081816
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
Review comment:
I'm not suggesting adding a separate "overview" doc page, my concern is: if we add the same content so much times, we need to consider adding it once in somewhere (that users visit most frequently, for example the "overview" of this whole chapter), and reference it when needed in other places. It's easy to maintain and keep consistent for a long run. We don't need to refine the same content many times manually in the future.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660474494
##########
File path: site2/docs/admin-api-overview.md
##########
@@ -9,15 +9,26 @@ The Pulsar admin interface enables you to manage all important entities in a Pul
You can interact with the admin interface via:
- HTTP calls, which are made against the admin {@inject: rest:REST:/} API provided by Pulsar brokers. For some RESTful APIs, they might be redirected to the owner brokers for serving with [`307 Temporary Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307), hence the HTTP callers should handle `307 Temporary Redirect`. If you use `curl` commands, you should specify `-L` to handle redirections.
+
+ > **Tip**
Review comment:
Updated these "tips" to "important" for keeping consistent.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] gmethvin commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
gmethvin commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660901858
##########
File path: site2/docs/admin-api-clusters.md
##########
@@ -4,14 +4,24 @@ title: Managing Clusters
sidebar_label: Clusters
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
Review comment:
Using a link with only the text "here" or "click here" is generally not good for UX. Usually it's best to have the text of the link describe the page the link goes to. An alternative would be something like:
> For the latest and most complete information about `pulsar-admin`, see [the pulsar-admin documentation](https://pulsar.apache.org/tools/pulsar-admin/)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870484037
@gmethvin @BewareMyPower many thanks for your comments. I've incorporated them, PTAL.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r661093014
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
Review comment:
@Jennifer88huang for this concern, I've replied before: https://github.com/apache/pulsar/pull/11146#issuecomment-870483161
I think this is a temporary workaround (to let users know the info quickly since many users have this issue and writers need to reply one by one), we may consider adding a floating window on the website, need more research later.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r661077717
##########
File path: site2/docs/admin-api-clusters.md
##########
@@ -4,14 +4,24 @@ title: Managing Clusters
sidebar_label: Clusters
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
Review comment:
Hi @gmethvin I've incorporated your comments, PTAL.
Since it's ok as-is, if no other comments, could you please help approve? Then users can get the info quickly.
We can do some research on the duplicated text and optimize the user experience later.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r661076142
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
+>
+> This page only shows **some frequently used operations**.
+>
+> - For the latest and complete information about `pulsar-admin`, including commands, flags, descriptions, and more, see [here](https://pulsar.apache.org/tools/pulsar-admin/).
+>
+> - For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see [here]{@inject: rest:REST:/}.
+>
+> - For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [here](https://pulsar.apache.org/api/admin/).
+
Pulsar brokers consist of two components:
1. An HTTP server exposing a {@inject: rest:REST:/} interface administration and [topic](reference-terminology.md#topic) lookup.
2. A dispatcher that handles all Pulsar [message](reference-terminology.md#message) transfers.
[Brokers](reference-terminology.md#broker) can be managed via:
-* The [`brokers`](reference-pulsar-admin.md#brokers) command of the [`pulsar-admin`](reference-pulsar-admin.md) tool
+* The `brokers` command of the [`pulsar-admin`](https://pulsar.apache.org/tools/pulsar-admin/) tool
Review comment:
That would be inconvenient for users to get info.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] gmethvin commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
gmethvin commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r661013541
##########
File path: site2/docs/admin-api-brokers.md
##########
@@ -4,16 +4,26 @@ title: Managing Brokers
sidebar_label: Brokers
---
+> **Important**
Review comment:
Are you suggesting putting it in a separate "overview" documentation page?
That doesn't really solve the problem here, which is to make sure someone who lands on this page is aware that it's not a complete description of all endpoints.
What if we just eliminate this page altogether and use the generated pages instead? I don't see why we need a separate "frequently used operations" page and another complete reference.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] tuteng edited a comment on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
tuteng edited a comment on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870446087
> I have another question that may not block the merge this PR.
>
> 
>
> Why are there only documents of SNAPSHOT versions? Do you know the reason? @tuteng
I think it is related to the https://github.com/apache/pulsar/blob/master/pom.xml#L35 configuration of the pom, It gets the version information through this script https://github.com/apache/pulsar/blob/master/site2/tools/pulsar-admin-doc-gen.sh#L22 @BewareMyPower
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a change in pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on a change in pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#discussion_r660472073
##########
File path: site2/docs/admin-api-namespaces.md
##########
@@ -905,7 +915,7 @@ admin.namespaces().removeDeduplicationSnapshotInterval(namespace)
### Namespace isolation
-Coming soon.
+You can use the Pulsar isolation policy to allocate resources (broker and bookie) for a namespace. For more information, see [here](administration-isolation.md).
Review comment:
OK. Done.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] BewareMyPower commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
BewareMyPower commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870429434
I have another question that may not block the merge this PR.
Why are there only documents of SNAPSHOT versions? Do you know the reason? @tuteng
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on pull request #11146: [Doc] Add descriptions for various API docs
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on pull request #11146:
URL: https://github.com/apache/pulsar/pull/11146#issuecomment-870465401
> Please replace HTTP links to HTTPS links. For example, replace http://pulsar.apache.org/tools/pulsar-admin/ to https://pulsar.apache.org/tools/pulsar-admin/
Thanks for your suggestion. Done.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org