You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pulsar.apache.org by Anonymitaet _ <an...@hotmail.com> on 2021/07/06 03:23:25 UTC
[Doc] generate docs from code automatically
Hi Pulsarers,
With the rapid adoption of Pulsar, our community is providing many features and enhancements for *Pulsar command-line tools* and *Pulsar configuration*, that is great!
Previously, the docs of them are updated *manually*, which is time-consuming and error-prone. To improve the productivity, effectiveness, and velocity of developing these contents, we are developing tools to *generate docs from source code files automatically*.
In this way, we can get the code and the doc to good enough quality on both sides in parallel and then merge both together so they end up shipping in the same release.
Below is the comparison of before and after. Here takes the docs of pulsar-client and pulsar-perf as examples.
# pulsar-client
- Previous: https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
- Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
# pulsar-perf
- Previous: https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
- Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
Obviously, this is a huge project. So far, we have completed some tasks and documented the progress and all details here: https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making this happen!
Anonymitaet
Re: [Doc] generate docs from code automatically
Posted by Anonymitaet _ <an...@hotmail.com>.
Hi Hang,
Many thanks for your support!
We have documented the progress and all details here: https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289, which contains good examples and references.
Let me know if you need any help.
From: Hang Chen <ch...@apache.org>
Reply-To: "users@pulsar.apache.org" <us...@pulsar.apache.org>
Date: Saturday, July 10, 2021 at 14:38
To: "dev@pulsar.apache.org" <de...@pulsar.apache.org>
Cc: pulsar-users <us...@pulsar.apache.org>
Subject: Re: [Doc] generate docs from code automatically
Great Job!
I'd like to participate in this work.
Thanks
Hang
Enrico Olivelli <eo...@gmail.com>> 于2021年7月10日周六 上午1:23写道：
Great initiative!
Thanks
Enrico
Il Ven 9 Lug 2021, 01:47 Guangning E <eg...@gmail.com>> ha scritto:
> Great start.
>
> Anonymitaet _ <an...@hotmail.com>> 于2021年7月8日周四 下午3:18写道：
>
>> Thanks Xiaolong, welcome to join us to build better content experience
>> for Pulsar users!
>>
>>
>>
>> *From: *"rxl@apache.org<ma...@apache.org>" <ra...@gmail.com>>
>> *Reply-To: *"users@pulsar.apache.org<ma...@pulsar.apache.org>" <us...@pulsar.apache.org>>
>> *Date: *Thursday, July 8, 2021 at 11:58
>> *To: *"users@pulsar.apache.org<ma...@pulsar.apache.org>" <us...@pulsar.apache.org>>
>> *Cc: *"dev@pulsar.apache.org<ma...@pulsar.apache.org>" <de...@pulsar.apache.org>>
>> *Subject: *Re: [Doc] generate docs from code automatically
>>
>>
>>
>> Thanks yu, it seems to be a good start, so that we can better ensure the
>> consistency of the code and documentation, rather than relying on
>> artificial methods to fix the consistency problem.
>>
>>
>>
>> Of course, I would be happy to participate if time permits.
>>
>>
>>
>> --
>>
>> Thanks
>>
>> Xiaolong Ran
>>
>>
>>
>> Anonymitaet _ <an...@hotmail.com>> 于2021年7月7日周三 上午12:01写道：
>>
>> Hi Pulsarers,
>>
>>
>>
>> With the rapid adoption of Pulsar, our community is providing many
>> features and enhancements for *Pulsar command-line tools* and *Pulsar
>> configuration*, that is great!
>>
>>
>>
>> Previously, the docs of them are updated *manually*, which is
>> time-consuming and error-prone. To improve the productivity, effectiveness,
>> and velocity of developing these contents, we are developing tools to
>> *generate docs from source code files automatically*.
>>
>>
>>
>> In this way, we can get the code and the doc to good enough quality on
>> both sides in parallel and then merge both together so they end up shipping
>> in the same release.
>>
>>
>>
>> Below is the comparison of before and after. Here takes the docs of
>> pulsar-client and pulsar-perf as examples.
>>
>>
>>
>> # pulsar-client
>>
>> - Previous:
>> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
>>
>> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
>>
>>
>>
>> # pulsar-perf
>>
>> - Previous:
>> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
>>
>> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
>>
>>
>>
>> Obviously, this is a huge project. So far, we have completed some tasks
>> and documented the progress and all details here:
>> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
>>
>>
>>
>> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
>>
>>
>>
>> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making
>> this happen!
>>
>>
>>
>> Anonymitaet
>>
>>
>>
>>
>>
>>
Re: [Doc] generate docs from code automatically
Posted by Anonymitaet _ <an...@hotmail.com>.
Hi Hang,
Many thanks for your support!
We have documented the progress and all details here: https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289, which contains good examples and references.
Let me know if you need any help.
From: Hang Chen <ch...@apache.org>
Reply-To: "users@pulsar.apache.org" <us...@pulsar.apache.org>
Date: Saturday, July 10, 2021 at 14:38
To: "dev@pulsar.apache.org" <de...@pulsar.apache.org>
Cc: pulsar-users <us...@pulsar.apache.org>
Subject: Re: [Doc] generate docs from code automatically
Great Job!
I'd like to participate in this work.
Thanks
Hang
Enrico Olivelli <eo...@gmail.com>> 于2021年7月10日周六 上午1:23写道：
Great initiative!
Thanks
Enrico
Il Ven 9 Lug 2021, 01:47 Guangning E <eg...@gmail.com>> ha scritto:
> Great start.
>
> Anonymitaet _ <an...@hotmail.com>> 于2021年7月8日周四 下午3:18写道：
>
>> Thanks Xiaolong, welcome to join us to build better content experience
>> for Pulsar users!
>>
>>
>>
>> *From: *"rxl@apache.org<ma...@apache.org>" <ra...@gmail.com>>
>> *Reply-To: *"users@pulsar.apache.org<ma...@pulsar.apache.org>" <us...@pulsar.apache.org>>
>> *Date: *Thursday, July 8, 2021 at 11:58
>> *To: *"users@pulsar.apache.org<ma...@pulsar.apache.org>" <us...@pulsar.apache.org>>
>> *Cc: *"dev@pulsar.apache.org<ma...@pulsar.apache.org>" <de...@pulsar.apache.org>>
>> *Subject: *Re: [Doc] generate docs from code automatically
>>
>>
>>
>> Thanks yu, it seems to be a good start, so that we can better ensure the
>> consistency of the code and documentation, rather than relying on
>> artificial methods to fix the consistency problem.
>>
>>
>>
>> Of course, I would be happy to participate if time permits.
>>
>>
>>
>> --
>>
>> Thanks
>>
>> Xiaolong Ran
>>
>>
>>
>> Anonymitaet _ <an...@hotmail.com>> 于2021年7月7日周三 上午12:01写道：
>>
>> Hi Pulsarers,
>>
>>
>>
>> With the rapid adoption of Pulsar, our community is providing many
>> features and enhancements for *Pulsar command-line tools* and *Pulsar
>> configuration*, that is great!
>>
>>
>>
>> Previously, the docs of them are updated *manually*, which is
>> time-consuming and error-prone. To improve the productivity, effectiveness,
>> and velocity of developing these contents, we are developing tools to
>> *generate docs from source code files automatically*.
>>
>>
>>
>> In this way, we can get the code and the doc to good enough quality on
>> both sides in parallel and then merge both together so they end up shipping
>> in the same release.
>>
>>
>>
>> Below is the comparison of before and after. Here takes the docs of
>> pulsar-client and pulsar-perf as examples.
>>
>>
>>
>> # pulsar-client
>>
>> - Previous:
>> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
>>
>> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
>>
>>
>>
>> # pulsar-perf
>>
>> - Previous:
>> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
>>
>> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
>>
>>
>>
>> Obviously, this is a huge project. So far, we have completed some tasks
>> and documented the progress and all details here:
>> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
>>
>>
>>
>> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
>>
>>
>>
>> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making
>> this happen!
>>
>>
>>
>> Anonymitaet
>>
>>
>>
>>
>>
>>
Re: [Doc] generate docs from code automatically
Posted by Hang Chen <ch...@apache.org>.
Great Job!
I'd like to participate in this work.
Thanks
Hang
Enrico Olivelli <eo...@gmail.com> 于2021年7月10日周六 上午1:23写道：
> Great initiative!
>
> Thanks
> Enrico
>
> Il Ven 9 Lug 2021, 01:47 Guangning E <eg...@gmail.com> ha scritto:
>
> > Great start.
> >
> > Anonymitaet _ <an...@hotmail.com> 于2021年7月8日周四 下午3:18写道：
> >
> >> Thanks Xiaolong, welcome to join us to build better content experience
> >> for Pulsar users!
> >>
> >>
> >>
> >> *From: *"rxl@apache.org" <ra...@gmail.com>
> >> *Reply-To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
> >> *Date: *Thursday, July 8, 2021 at 11:58
> >> *To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
> >> *Cc: *"dev@pulsar.apache.org" <de...@pulsar.apache.org>
> >> *Subject: *Re: [Doc] generate docs from code automatically
> >>
> >>
> >>
> >> Thanks yu, it seems to be a good start, so that we can better ensure the
> >> consistency of the code and documentation, rather than relying on
> >> artificial methods to fix the consistency problem.
> >>
> >>
> >>
> >> Of course, I would be happy to participate if time permits.
> >>
> >>
> >>
> >> --
> >>
> >> Thanks
> >>
> >> Xiaolong Ran
> >>
> >>
> >>
> >> Anonymitaet _ <an...@hotmail.com> 于2021年7月7日周三 上午12:01写道：
> >>
> >> Hi Pulsarers,
> >>
> >>
> >>
> >> With the rapid adoption of Pulsar, our community is providing many
> >> features and enhancements for *Pulsar command-line tools* and *Pulsar
> >> configuration*, that is great!
> >>
> >>
> >>
> >> Previously, the docs of them are updated *manually*, which is
> >> time-consuming and error-prone. To improve the productivity,
> effectiveness,
> >> and velocity of developing these contents, we are developing tools to
> >> *generate docs from source code files automatically*.
> >>
> >>
> >>
> >> In this way, we can get the code and the doc to good enough quality on
> >> both sides in parallel and then merge both together so they end up
> shipping
> >> in the same release.
> >>
> >>
> >>
> >> Below is the comparison of before and after. Here takes the docs of
> >> pulsar-client and pulsar-perf as examples.
> >>
> >>
> >>
> >> # pulsar-client
> >>
> >> - Previous:
> >>
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
> >>
> >> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
> >>
> >>
> >>
> >> # pulsar-perf
> >>
> >> - Previous:
> >> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
> >>
> >> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
> >>
> >>
> >>
> >> Obviously, this is a huge project. So far, we have completed some tasks
> >> and documented the progress and all details here:
> >>
> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
> >>
> >>
> >>
> >> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback
> here!
> >>
> >>
> >>
> >> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for
> making
> >> this happen!
> >>
> >>
> >>
> >> Anonymitaet
> >>
> >>
> >>
> >>
> >>
> >>
>
Re: [Doc] generate docs from code automatically
Posted by Hang Chen <ch...@apache.org>.
Great Job!
I'd like to participate in this work.
Thanks
Hang
Enrico Olivelli <eo...@gmail.com> 于2021年7月10日周六 上午1:23写道：
> Great initiative!
>
> Thanks
> Enrico
>
> Il Ven 9 Lug 2021, 01:47 Guangning E <eg...@gmail.com> ha scritto:
>
> > Great start.
> >
> > Anonymitaet _ <an...@hotmail.com> 于2021年7月8日周四 下午3:18写道：
> >
> >> Thanks Xiaolong, welcome to join us to build better content experience
> >> for Pulsar users!
> >>
> >>
> >>
> >> *From: *"rxl@apache.org" <ra...@gmail.com>
> >> *Reply-To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
> >> *Date: *Thursday, July 8, 2021 at 11:58
> >> *To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
> >> *Cc: *"dev@pulsar.apache.org" <de...@pulsar.apache.org>
> >> *Subject: *Re: [Doc] generate docs from code automatically
> >>
> >>
> >>
> >> Thanks yu, it seems to be a good start, so that we can better ensure the
> >> consistency of the code and documentation, rather than relying on
> >> artificial methods to fix the consistency problem.
> >>
> >>
> >>
> >> Of course, I would be happy to participate if time permits.
> >>
> >>
> >>
> >> --
> >>
> >> Thanks
> >>
> >> Xiaolong Ran
> >>
> >>
> >>
> >> Anonymitaet _ <an...@hotmail.com> 于2021年7月7日周三 上午12:01写道：
> >>
> >> Hi Pulsarers,
> >>
> >>
> >>
> >> With the rapid adoption of Pulsar, our community is providing many
> >> features and enhancements for *Pulsar command-line tools* and *Pulsar
> >> configuration*, that is great!
> >>
> >>
> >>
> >> Previously, the docs of them are updated *manually*, which is
> >> time-consuming and error-prone. To improve the productivity,
> effectiveness,
> >> and velocity of developing these contents, we are developing tools to
> >> *generate docs from source code files automatically*.
> >>
> >>
> >>
> >> In this way, we can get the code and the doc to good enough quality on
> >> both sides in parallel and then merge both together so they end up
> shipping
> >> in the same release.
> >>
> >>
> >>
> >> Below is the comparison of before and after. Here takes the docs of
> >> pulsar-client and pulsar-perf as examples.
> >>
> >>
> >>
> >> # pulsar-client
> >>
> >> - Previous:
> >>
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
> >>
> >> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
> >>
> >>
> >>
> >> # pulsar-perf
> >>
> >> - Previous:
> >> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
> >>
> >> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
> >>
> >>
> >>
> >> Obviously, this is a huge project. So far, we have completed some tasks
> >> and documented the progress and all details here:
> >>
> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
> >>
> >>
> >>
> >> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback
> here!
> >>
> >>
> >>
> >> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for
> making
> >> this happen!
> >>
> >>
> >>
> >> Anonymitaet
> >>
> >>
> >>
> >>
> >>
> >>
>
Re: [Doc] generate docs from code automatically
Posted by Enrico Olivelli <eo...@gmail.com>.
Great initiative!
Thanks
Enrico
Il Ven 9 Lug 2021, 01:47 Guangning E <eg...@gmail.com> ha scritto:
> Great start.
>
> Anonymitaet _ <an...@hotmail.com> 于2021年7月8日周四 下午3:18写道：
>
>> Thanks Xiaolong, welcome to join us to build better content experience
>> for Pulsar users!
>>
>>
>>
>> *From: *"rxl@apache.org" <ra...@gmail.com>
>> *Reply-To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
>> *Date: *Thursday, July 8, 2021 at 11:58
>> *To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
>> *Cc: *"dev@pulsar.apache.org" <de...@pulsar.apache.org>
>> *Subject: *Re: [Doc] generate docs from code automatically
>>
>>
>>
>> Thanks yu, it seems to be a good start, so that we can better ensure the
>> consistency of the code and documentation, rather than relying on
>> artificial methods to fix the consistency problem.
>>
>>
>>
>> Of course, I would be happy to participate if time permits.
>>
>>
>>
>> --
>>
>> Thanks
>>
>> Xiaolong Ran
>>
>>
>>
>> Anonymitaet _ <an...@hotmail.com> 于2021年7月7日周三 上午12:01写道：
>>
>> Hi Pulsarers,
>>
>>
>>
>> With the rapid adoption of Pulsar, our community is providing many
>> features and enhancements for *Pulsar command-line tools* and *Pulsar
>> configuration*, that is great!
>>
>>
>>
>> Previously, the docs of them are updated *manually*, which is
>> time-consuming and error-prone. To improve the productivity, effectiveness,
>> and velocity of developing these contents, we are developing tools to
>> *generate docs from source code files automatically*.
>>
>>
>>
>> In this way, we can get the code and the doc to good enough quality on
>> both sides in parallel and then merge both together so they end up shipping
>> in the same release.
>>
>>
>>
>> Below is the comparison of before and after. Here takes the docs of
>> pulsar-client and pulsar-perf as examples.
>>
>>
>>
>> # pulsar-client
>>
>> - Previous:
>> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
>>
>> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
>>
>>
>>
>> # pulsar-perf
>>
>> - Previous:
>> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
>>
>> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
>>
>>
>>
>> Obviously, this is a huge project. So far, we have completed some tasks
>> and documented the progress and all details here:
>> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
>>
>>
>>
>> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
>>
>>
>>
>> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making
>> this happen!
>>
>>
>>
>> Anonymitaet
>>
>>
>>
>>
>>
>>
Re: [Doc] generate docs from code automatically
Posted by Enrico Olivelli <eo...@gmail.com>.
Great initiative!
Thanks
Enrico
Il Ven 9 Lug 2021, 01:47 Guangning E <eg...@gmail.com> ha scritto:
> Great start.
>
> Anonymitaet _ <an...@hotmail.com> 于2021年7月8日周四 下午3:18写道：
>
>> Thanks Xiaolong, welcome to join us to build better content experience
>> for Pulsar users!
>>
>>
>>
>> *From: *"rxl@apache.org" <ra...@gmail.com>
>> *Reply-To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
>> *Date: *Thursday, July 8, 2021 at 11:58
>> *To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
>> *Cc: *"dev@pulsar.apache.org" <de...@pulsar.apache.org>
>> *Subject: *Re: [Doc] generate docs from code automatically
>>
>>
>>
>> Thanks yu, it seems to be a good start, so that we can better ensure the
>> consistency of the code and documentation, rather than relying on
>> artificial methods to fix the consistency problem.
>>
>>
>>
>> Of course, I would be happy to participate if time permits.
>>
>>
>>
>> --
>>
>> Thanks
>>
>> Xiaolong Ran
>>
>>
>>
>> Anonymitaet _ <an...@hotmail.com> 于2021年7月7日周三 上午12:01写道：
>>
>> Hi Pulsarers,
>>
>>
>>
>> With the rapid adoption of Pulsar, our community is providing many
>> features and enhancements for *Pulsar command-line tools* and *Pulsar
>> configuration*, that is great!
>>
>>
>>
>> Previously, the docs of them are updated *manually*, which is
>> time-consuming and error-prone. To improve the productivity, effectiveness,
>> and velocity of developing these contents, we are developing tools to
>> *generate docs from source code files automatically*.
>>
>>
>>
>> In this way, we can get the code and the doc to good enough quality on
>> both sides in parallel and then merge both together so they end up shipping
>> in the same release.
>>
>>
>>
>> Below is the comparison of before and after. Here takes the docs of
>> pulsar-client and pulsar-perf as examples.
>>
>>
>>
>> # pulsar-client
>>
>> - Previous:
>> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
>>
>> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
>>
>>
>>
>> # pulsar-perf
>>
>> - Previous:
>> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
>>
>> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
>>
>>
>>
>> Obviously, this is a huge project. So far, we have completed some tasks
>> and documented the progress and all details here:
>> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
>>
>>
>>
>> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
>>
>>
>>
>> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making
>> this happen!
>>
>>
>>
>> Anonymitaet
>>
>>
>>
>>
>>
>>
Re: [Doc] generate docs from code automatically
Posted by Guangning E <eg...@gmail.com>.
Great start.
Anonymitaet _ <an...@hotmail.com> 于2021年7月8日周四 下午3:18写道：
> Thanks Xiaolong, welcome to join us to build better content experience for
> Pulsar users!
>
>
>
> *From: *"rxl@apache.org" <ra...@gmail.com>
> *Reply-To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
> *Date: *Thursday, July 8, 2021 at 11:58
> *To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
> *Cc: *"dev@pulsar.apache.org" <de...@pulsar.apache.org>
> *Subject: *Re: [Doc] generate docs from code automatically
>
>
>
> Thanks yu, it seems to be a good start, so that we can better ensure the
> consistency of the code and documentation, rather than relying on
> artificial methods to fix the consistency problem.
>
>
>
> Of course, I would be happy to participate if time permits.
>
>
>
> --
>
> Thanks
>
> Xiaolong Ran
>
>
>
> Anonymitaet _ <an...@hotmail.com> 于2021年7月7日周三 上午12:01写道：
>
> Hi Pulsarers,
>
>
>
> With the rapid adoption of Pulsar, our community is providing many
> features and enhancements for *Pulsar command-line tools* and *Pulsar
> configuration*, that is great!
>
>
>
> Previously, the docs of them are updated *manually*, which is
> time-consuming and error-prone. To improve the productivity, effectiveness,
> and velocity of developing these contents, we are developing tools to
> *generate docs from source code files automatically*.
>
>
>
> In this way, we can get the code and the doc to good enough quality on
> both sides in parallel and then merge both together so they end up shipping
> in the same release.
>
>
>
> Below is the comparison of before and after. Here takes the docs of
> pulsar-client and pulsar-perf as examples.
>
>
>
> # pulsar-client
>
> - Previous:
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
>
> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
>
>
>
> # pulsar-perf
>
> - Previous:
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
>
> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
>
>
>
> Obviously, this is a huge project. So far, we have completed some tasks
> and documented the progress and all details here:
> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
>
>
>
> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
>
>
>
> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making
> this happen!
>
>
>
> Anonymitaet
>
>
>
>
>
>
Re: [Doc] generate docs from code automatically
Posted by Guangning E <eg...@gmail.com>.
Great start.
Anonymitaet _ <an...@hotmail.com> 于2021年7月8日周四 下午3:18写道：
> Thanks Xiaolong, welcome to join us to build better content experience for
> Pulsar users!
>
>
>
> *From: *"rxl@apache.org" <ra...@gmail.com>
> *Reply-To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
> *Date: *Thursday, July 8, 2021 at 11:58
> *To: *"users@pulsar.apache.org" <us...@pulsar.apache.org>
> *Cc: *"dev@pulsar.apache.org" <de...@pulsar.apache.org>
> *Subject: *Re: [Doc] generate docs from code automatically
>
>
>
> Thanks yu, it seems to be a good start, so that we can better ensure the
> consistency of the code and documentation, rather than relying on
> artificial methods to fix the consistency problem.
>
>
>
> Of course, I would be happy to participate if time permits.
>
>
>
> --
>
> Thanks
>
> Xiaolong Ran
>
>
>
> Anonymitaet _ <an...@hotmail.com> 于2021年7月7日周三 上午12:01写道：
>
> Hi Pulsarers,
>
>
>
> With the rapid adoption of Pulsar, our community is providing many
> features and enhancements for *Pulsar command-line tools* and *Pulsar
> configuration*, that is great!
>
>
>
> Previously, the docs of them are updated *manually*, which is
> time-consuming and error-prone. To improve the productivity, effectiveness,
> and velocity of developing these contents, we are developing tools to
> *generate docs from source code files automatically*.
>
>
>
> In this way, we can get the code and the doc to good enough quality on
> both sides in parallel and then merge both together so they end up shipping
> in the same release.
>
>
>
> Below is the comparison of before and after. Here takes the docs of
> pulsar-client and pulsar-perf as examples.
>
>
>
> # pulsar-client
>
> - Previous:
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
>
> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
>
>
>
> # pulsar-perf
>
> - Previous:
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
>
> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
>
>
>
> Obviously, this is a huge project. So far, we have completed some tasks
> and documented the progress and all details here:
> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
>
>
>
> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
>
>
>
> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making
> this happen!
>
>
>
> Anonymitaet
>
>
>
>
>
>
Re: [Doc] generate docs from code automatically
Posted by Anonymitaet _ <an...@hotmail.com>.
Thanks Xiaolong, welcome to join us to build better content experience for Pulsar users!
From: "rxl@apache.org" <ra...@gmail.com>
Reply-To: "users@pulsar.apache.org" <us...@pulsar.apache.org>
Date: Thursday, July 8, 2021 at 11:58
To: "users@pulsar.apache.org" <us...@pulsar.apache.org>
Cc: "dev@pulsar.apache.org" <de...@pulsar.apache.org>
Subject: Re: [Doc] generate docs from code automatically
Thanks yu, it seems to be a good start, so that we can better ensure the consistency of the code and documentation, rather than relying on artificial methods to fix the consistency problem.
Of course, I would be happy to participate if time permits.
--
Thanks
Xiaolong Ran
Anonymitaet _ <an...@hotmail.com>> 于2021年7月7日周三 上午12:01写道：
Hi Pulsarers,
With the rapid adoption of Pulsar, our community is providing many features and enhancements for *Pulsar command-line tools* and *Pulsar configuration*, that is great!
Previously, the docs of them are updated *manually*, which is time-consuming and error-prone. To improve the productivity, effectiveness, and velocity of developing these contents, we are developing tools to *generate docs from source code files automatically*.
In this way, we can get the code and the doc to good enough quality on both sides in parallel and then merge both together so they end up shipping in the same release.
Below is the comparison of before and after. Here takes the docs of pulsar-client and pulsar-perf as examples.
# pulsar-client
- Previous: https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
- Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
# pulsar-perf
- Previous: https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
- Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
Obviously, this is a huge project. So far, we have completed some tasks and documented the progress and all details here: https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making this happen!
Anonymitaet
Re: [Doc] generate docs from code automatically
Posted by Anonymitaet _ <an...@hotmail.com>.
Thanks Xiaolong, welcome to join us to build better content experience for Pulsar users!
From: "rxl@apache.org" <ra...@gmail.com>
Reply-To: "users@pulsar.apache.org" <us...@pulsar.apache.org>
Date: Thursday, July 8, 2021 at 11:58
To: "users@pulsar.apache.org" <us...@pulsar.apache.org>
Cc: "dev@pulsar.apache.org" <de...@pulsar.apache.org>
Subject: Re: [Doc] generate docs from code automatically
Thanks yu, it seems to be a good start, so that we can better ensure the consistency of the code and documentation, rather than relying on artificial methods to fix the consistency problem.
Of course, I would be happy to participate if time permits.
--
Thanks
Xiaolong Ran
Anonymitaet _ <an...@hotmail.com>> 于2021年7月7日周三 上午12:01写道：
Hi Pulsarers,
With the rapid adoption of Pulsar, our community is providing many features and enhancements for *Pulsar command-line tools* and *Pulsar configuration*, that is great!
Previously, the docs of them are updated *manually*, which is time-consuming and error-prone. To improve the productivity, effectiveness, and velocity of developing these contents, we are developing tools to *generate docs from source code files automatically*.
In this way, we can get the code and the doc to good enough quality on both sides in parallel and then merge both together so they end up shipping in the same release.
Below is the comparison of before and after. Here takes the docs of pulsar-client and pulsar-perf as examples.
# pulsar-client
- Previous: https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
- Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
# pulsar-perf
- Previous: https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
- Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
Obviously, this is a huge project. So far, we have completed some tasks and documented the progress and all details here: https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making this happen!
Anonymitaet
Re: [Doc] generate docs from code automatically
Posted by "rxl@apache.org" <ra...@gmail.com>.
Thanks yu, it seems to be a good start, so that we can better ensure the
consistency of the code and documentation, rather than relying on
artificial methods to fix the consistency problem.
Of course, I would be happy to participate if time permits.
--
Thanks
Xiaolong Ran
Anonymitaet _ <an...@hotmail.com> 于2021年7月7日周三 上午12:01写道：
> Hi Pulsarers,
>
>
>
> With the rapid adoption of Pulsar, our community is providing many
> features and enhancements for *Pulsar command-line tools* and *Pulsar
> configuration*, that is great!
>
>
>
> Previously, the docs of them are updated *manually*, which is
> time-consuming and error-prone. To improve the productivity, effectiveness,
> and velocity of developing these contents, we are developing tools to
> *generate docs from source code files automatically*.
>
>
>
> In this way, we can get the code and the doc to good enough quality on
> both sides in parallel and then merge both together so they end up shipping
> in the same release.
>
>
>
> Below is the comparison of before and after. Here takes the docs of
> pulsar-client and pulsar-perf as examples.
>
>
>
> # pulsar-client
>
> - Previous:
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
>
> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
>
>
>
> # pulsar-perf
>
> - Previous:
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
>
> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
>
>
>
> Obviously, this is a huge project. So far, we have completed some tasks
> and documented the progress and all details here:
> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
>
>
>
> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
>
>
>
> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making
> this happen!
>
>
>
> Anonymitaet
>
>
>
>
>
Re: [Doc] generate docs from code automatically
Posted by "rxl@apache.org" <ra...@gmail.com>.
Thanks yu, it seems to be a good start, so that we can better ensure the
consistency of the code and documentation, rather than relying on
artificial methods to fix the consistency problem.
Of course, I would be happy to participate if time permits.
--
Thanks
Xiaolong Ran
Anonymitaet _ <an...@hotmail.com> 于2021年7月7日周三 上午12:01写道：
> Hi Pulsarers,
>
>
>
> With the rapid adoption of Pulsar, our community is providing many
> features and enhancements for *Pulsar command-line tools* and *Pulsar
> configuration*, that is great!
>
>
>
> Previously, the docs of them are updated *manually*, which is
> time-consuming and error-prone. To improve the productivity, effectiveness,
> and velocity of developing these contents, we are developing tools to
> *generate docs from source code files automatically*.
>
>
>
> In this way, we can get the code and the doc to good enough quality on
> both sides in parallel and then merge both together so they end up shipping
> in the same release.
>
>
>
> Below is the comparison of before and after. Here takes the docs of
> pulsar-client and pulsar-perf as examples.
>
>
>
> # pulsar-client
>
> - Previous:
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-client
>
> - Now: http://pulsar.apache.org/tools/pulsar-client/2.9.0-SNAPSHOT/
>
>
>
> # pulsar-perf
>
> - Previous:
> https://pulsar.apache.org/docs/en/next/reference-cli-tools/#pulsar-perf
>
> - Now: http://pulsar.apache.org/tools/pulsar-perf/2.9.0-SNAPSHOT/
>
>
>
> Obviously, this is a huge project. So far, we have completed some tasks
> and documented the progress and all details here:
> https://docs.google.com/spreadsheets/d/1P6tePGmU1lEhGKY_hE3JWgJ1rUTBCmW7AshDICJZr3o/edit#gid=1030826289
>
>
>
> Feel free to comment or CONTRIBUTE TOGETHER, we'd love your feedback here!
>
>
>
> P.S. Special thanks goes to tuteng, urfreespace, and 315157973 for making
> this happen!
>
>
>
> Anonymitaet
>
>
>
>
>