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 2022/10/14 09:16:08 UTC

[GitHub] [pulsar] Anonymitaet opened a new pull request, #18051: [feat][doc] Separate CLI docs for doc gen automation

Anonymitaet opened a new pull request, #18051:
URL: https://github.com/apache/pulsar/pull/18051

   This is part work of [PIP 78: Generate Docs from Code Automatically](https://docs.google.com/document/d/18kCBG5nyp0BsscFDyQyUERHrCMRcKmzyk1RMaD4hECg/edit)
   
   Docs in the green circle are updated manually and shown independently on https://pulsar.apache.org/reference/#/latest/, so do not care about the metadata in .md files.
   
   <img width="846" alt="image" src="https://user-images.githubusercontent.com/50226895/195809297-11a0f0d8-c47f-4658-a85e-a87d9096653d.png">
   
   Metadata example:
   
   ```
   ---
   id: reference-cli-pulsar-shell
   title: Pulsar CLI tools - pulsar-shell
   sidebar_label: "cli-pulsar-shell"
   ---
   ```
   
   ### Documentation
   
   <!-- DO NOT REMOVE THIS SECTION. CHECK THE PROPER BOX ONLY. -->
   
   - [x] `doc` <!-- Your PR contains doc changes. Please attach the local preview screenshots (run `sh start.sh` at `pulsar/site2/website`) to your PR description, or else your PR might not get merged. -->
   


-- 
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 #18051: [feat][doc] Separate CLI docs for doc gen automation

Posted by GitBox <gi...@apache.org>.
Anonymitaet merged PR #18051:
URL: https://github.com/apache/pulsar/pull/18051


-- 
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] tisonkun commented on a diff in pull request #18051: [feat][doc] Separate CLI docs for doc gen automation

Posted by GitBox <gi...@apache.org>.
tisonkun commented on code in PR #18051:
URL: https://github.com/apache/pulsar/pull/18051#discussion_r996928487


##########
site2/docs/reference-cli-tools.md:
##########
@@ -6,1066 +6,21 @@ sidebar_label: "Pulsar CLI tools"
 
 Pulsar offers several command-line tools that you can use for managing Pulsar installations, performance testing, using command-line producers and consumers, and more.
 
-All Pulsar command-line tools can be run from the `bin` directory of your [installed Pulsar package](getting-started-standalone.md). The following tools are currently documented:
+* [`pulsar-admin`](https://pulsar.apache.org/reference/#/latest/pulsar-admin/)
+* [`pulsar`](https://pulsar.apache.org/reference/#/latest/pulsar/)
+* [`pulsar-client`](https://pulsar.apache.org/reference/#/latest/pulsar-client/)
+* [`pulsar-perf`](https://pulsar.apache.org/reference/#/latest/pulsar-perf/)

Review Comment:
   1. We'd better use `/reference` than `https://pulsar.apache.org/reference` here.
   2. We should find a way to generate version part (`latest`) so that when the next version become a stable version, it doesn't direct users to the latest reference pages.



-- 
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] tisonkun commented on a diff in pull request #18051: [feat][doc] Separate CLI docs for doc gen automation

Posted by GitBox <gi...@apache.org>.
tisonkun commented on code in PR #18051:
URL: https://github.com/apache/pulsar/pull/18051#discussion_r996931626


##########
site2/docs/reference-cli-tools.md:
##########
@@ -6,1066 +6,21 @@ sidebar_label: "Pulsar CLI tools"
 
 Pulsar offers several command-line tools that you can use for managing Pulsar installations, performance testing, using command-line producers and consumers, and more.
 
-All Pulsar command-line tools can be run from the `bin` directory of your [installed Pulsar package](getting-started-standalone.md). The following tools are currently documented:
+* [`pulsar-admin`](https://pulsar.apache.org/reference/#/latest/pulsar-admin/)
+* [`pulsar`](https://pulsar.apache.org/reference/#/latest/pulsar/)
+* [`pulsar-client`](https://pulsar.apache.org/reference/#/latest/pulsar-client/)
+* [`pulsar-perf`](https://pulsar.apache.org/reference/#/latest/pulsar-perf/)

Review Comment:
   Perhaps we can use `@pulsar:version@` magic var but I think it cannot be resolved as `latest`. Maybe `@pulsar:docversion`? But there will be an issue between `latest` and `next`. We should unify names here.



-- 
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 #18051: [feat][doc] Separate CLI docs for doc gen automation

Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #18051:
URL: https://github.com/apache/pulsar/pull/18051#issuecomment-1280297019

   FYI: @SignorMercurio @urfreespace 
   
   I've confirmed with @codelipenghui, `broker-tool` is moved to [`pulsar-admin broker-stats`](https://pulsar.apache.org/reference/#/latest/pulsar-admin/broker-stats)
   
   <img width="1919" alt="image" src="https://user-images.githubusercontent.com/50226895/196093918-456d88bf-d272-46d7-abe9-361625517321.png">
   
   So I'll remove `reference-cli-broker-tool.md`, which means [this section](https://pulsar.staged.apache.org/docs/en/next/reference-cli-tools/#broker-tool) will not be available on the Reference site.
   <img width="1561" alt="image" src="https://user-images.githubusercontent.com/50226895/196094166-ef13526f-2ba9-4611-b374-eea359e66ca9.png">
   
   


-- 
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 #18051: [feat][doc] Separate CLI docs for doc gen automation

Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #18051:
URL: https://github.com/apache/pulsar/pull/18051#issuecomment-1278744729

   @SignorMercurio
   
   1. Could you please review this PR from a technical perspective? Thank you!
   
   2. Once this PR gets merged, we need to show the content (in the green box) on https://pulsar.apache.org/reference/#/latest/ ASAP? Or else users can not see them
   
   cc @D-2-Ed @DaveDuggins 


-- 
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] tisonkun commented on a diff in pull request #18051: [feat][doc] Separate CLI docs for doc gen automation

Posted by GitBox <gi...@apache.org>.
tisonkun commented on code in PR #18051:
URL: https://github.com/apache/pulsar/pull/18051#discussion_r998848468


##########
site2/docs/reference-cli-tools.md:
##########
@@ -6,1066 +6,21 @@ sidebar_label: "Pulsar CLI tools"
 
 Pulsar offers several command-line tools that you can use for managing Pulsar installations, performance testing, using command-line producers and consumers, and more.
 
-All Pulsar command-line tools can be run from the `bin` directory of your [installed Pulsar package](getting-started-standalone.md). The following tools are currently documented:
+* [`pulsar-admin`](https://pulsar.apache.org/reference/#/latest/pulsar-admin/)
+* [`pulsar`](https://pulsar.apache.org/reference/#/latest/pulsar/)
+* [`pulsar-client`](https://pulsar.apache.org/reference/#/latest/pulsar-client/)
+* [`pulsar-perf`](https://pulsar.apache.org/reference/#/latest/pulsar-perf/)

Review Comment:
   @SignorMercurio Let's do the first part.
   
   I'm thinking of that you can directly move the `docsify` folder under `website-next/static/` and we can preview the references pages also. You can give it a try. And perhaps several build logics should be modified.



-- 
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] SignorMercurio commented on a diff in pull request #18051: [feat][doc] Separate CLI docs for doc gen automation

Posted by GitBox <gi...@apache.org>.
SignorMercurio commented on code in PR #18051:
URL: https://github.com/apache/pulsar/pull/18051#discussion_r998840842


##########
site2/docs/reference-cli-tools.md:
##########
@@ -6,1066 +6,21 @@ sidebar_label: "Pulsar CLI tools"
 
 Pulsar offers several command-line tools that you can use for managing Pulsar installations, performance testing, using command-line producers and consumers, and more.
 
-All Pulsar command-line tools can be run from the `bin` directory of your [installed Pulsar package](getting-started-standalone.md). The following tools are currently documented:
+* [`pulsar-admin`](https://pulsar.apache.org/reference/#/latest/pulsar-admin/)
+* [`pulsar`](https://pulsar.apache.org/reference/#/latest/pulsar/)
+* [`pulsar-client`](https://pulsar.apache.org/reference/#/latest/pulsar-client/)
+* [`pulsar-perf`](https://pulsar.apache.org/reference/#/latest/pulsar-perf/)

Review Comment:
   We can change `latest` to `next`, but may not be able to use `/reference` as it may be parsed by Docusaurus as a markdown docs rather than an external link to another site.



-- 
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