You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pulsar.apache.org by GitBox <gi...@apache.org> on 2022/08/25 02:49:37 UTC
[GitHub] [pulsar-site] SignorMercurio opened a new pull request, #176: Generate client config docs from source code
SignorMercurio opened a new pull request, #176:
URL: https://github.com/apache/pulsar-site/pull/176
Related PR: apache/pulsar#17198.
@urfreespace 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: dev-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] SignorMercurio commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
SignorMercurio commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1233770325
> Will this generate correct docs for each official version of Pulsar?
This should generate correct docs for the latest version of Pulsar, since it depends on the current version of code.
> These generated docs only need to be run each time there is a new release.
For now, the generation script will be run during website build (in pulsar-site repo).
> Otherwise, we will end up with docs that mention configurations which might not be available.
I plan to create another PR in pulsar-site repo to deal with the versioning issue. I'll also check and correct the outdated links in the docs afterwards.
--
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: dev-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] michaeljmarshall commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
michaeljmarshall commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1238913866
Thanks for your explanation @Anonymitaet.
> It may not cause confusion since many projects follow this way (as below). Users get used to it and they know the meaning of `latest`.
I thought `latest` pointed to the "latest official release", and that the value of using `latest` is that your link will always point to the current latest release. For example, in the Cassandra link you shared, the right side shows that the docs are for version 4.1, even though the URL uses `latest`. In the drop down menu, it lets you select `master`, `trunk`, and several other versions. The Chaos Mesh website seems to use `next` to mean `master`, just like the Pulsar website, but the Chaos Mesh page warns users with a banner stating `This is unreleased documentation for Chaos Mesh Next version.`.
> Pulsar documentation and website iterate fast and those changes are shown on `latest`. It's a good chance for users to capture fresh updates and for maintainers to promote new changes.
I agree that it is helpful to give contributors a way to view their contributions, and I will modify what I said earlier about not putting that content on the website. It's okay to put it on the website, but I think we should make it clear that it is based on `master` version, which is not released yet. 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-site] urfreespace commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
urfreespace commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1233838116
> Yes, it's relevant for `website-next`, and can also generate docs for `website` as `WEBSITE` variable is controllable. I'm not sure whether the current configuration in the documentation is unreleased.
@SignorMercurio in fact, @michaeljmarshall means the next version docs but not `website-next` directory, I think he means your configuration docs is generated based on the master branch, and the master branch is not a released branch, however @Anonymitaet how do you think? /cc @michaeljmarshall
<img width="1418" alt="image" src="https://user-images.githubusercontent.com/76024046/187852454-f3c9d34a-f2fc-4595-9335-0184e489f56c.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: dev-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] SignorMercurio commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
SignorMercurio commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1233802014
Yes, it relevant for `website-next`, and can also generate docs for `website` as `WEBSITE` variable is controllable. I'm not sure whether the current configuration in the documentation is unreleased.
--
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: dev-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] Anonymitaet commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1239013191
@michaeljmarshall thanks!
> but I think we should make it clear that it is based on master version, which is not released yet.
- [Docusausus](https://docusaurus.io/docs/next) shows this hint, which seems a default feature of this framework. So In the beginning, Pulsar has this as well, but it was removed later because the word `latest` is ambiguous. Some ppl think it refers to `latest official release`, while others think it means `latest version (master)`.
- And why show this hint on Pulsar? Does it provide any helpful info to users? Does `unreleased documentation` mean `unsafe` or something else? If users use a certain Pulsar version, they're likely to choose the doc version first and then start reading. They might not care whether it is released or unreleased docs. Thoughts?
<img width="1701" alt="image" src="https://user-images.githubusercontent.com/50226895/188813307-3f4c87e3-b5d1-47a0-b57f-89cdd670fd30.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-site] michaeljmarshall commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
michaeljmarshall commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1233776155
I started work here https://github.com/apache/pulsar-site/pull/133 to make the generated docs based on released versions of Pulsar. If you look at the script in `site2/tools/release/javadoc-gen.sh`, you'll see that it downloads an official release of Pulsar and generates the docs from that source code. I think it is really important to have the versioned docs work correctly.
Is this PR relevant for the `next` version of the website? In my opinion, these `next` docs are confusing to users since they document features that are not yet released.
I don't really think we should be exposing the unreleased configuration documentation for the current `master` branch on the `pulsar.apache.org` website.
--
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: dev-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] Anonymitaet commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1239117640
I'll merge this PR after https://github.com/apache/pulsar/pull/17198 gets 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-site] Anonymitaet commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1233989322
@michaeljmarshall
> In my opinion, these next docs are confusing to users since they document features that are not yet released.
> I don't really think we should be exposing the unreleased configuration documentation for the current master branch on the pulsar.apache.org website.
I think it's OK to show the `latest` docs. Reasons:
1. It may not cause confusion since many projects follow this way (as below). Users get used to it and they know the meaning of `latest`.
Examples:
- https://chaos-mesh.org/docs/next/
- https://cassandra.apache.org/doc/latest/
- https://docs.taichi-lang.org/docs/master/
- https://skywalking.apache.org/docs/main/latest/en/concepts-and-designs/overview/
2. Pulsar documentation and website iterate fast and those changes are shown on `latest`. It's a good chance for users to capture fresh updates and for maintainers to promote new changes.
--
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: dev-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] Anonymitaet merged pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
Anonymitaet merged PR #176:
URL: https://github.com/apache/pulsar-site/pull/176
--
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-site] Anonymitaet commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1226745537
@urfreespace
Could you please review this PR from a technical perspective?
Thank you! 😊
--
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: dev-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] urfreespace commented on pull request #176: Generate client config docs from source code
Posted by GitBox <gi...@apache.org>.
urfreespace commented on PR #176:
URL: https://github.com/apache/pulsar-site/pull/176#issuecomment-1233630840
@SignorMercurio some conflicts need to be resolved, PTAL 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: dev-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org