[DISCUSS] Move all generated documentation to apache/pulsar-site repo

[Michael Marshall <mm...@apache.org>]

Hi Pulsar Community,

I would like to discuss changing where our generated docs are stored.

Currently, we keep some generated docs, like the python client docs
and the swagger docs, in our apache/pulsar repo. There are other docs
that are generated and stored in our apache/pulsar-site repo.

I propose that we move all generated docs to be stored in the
apache/pulsar-site repo. This change will primarily affect release
managers since they will need to push commits to the pulsar-site repo.
No one else should need to modify generated docs.

My primary motivation is that I'd like to add new generated Javadoc
pages for all of our recent releases so that we no longer only serve
"-SNAPSHOT" versions of the generated docs. Those new docs will
increase the size of our apache/pulsar repo. I prefer to keep the
apache/pulsar repo small.

I plan to open a PR to move these docs from the apache/pulsar repo to
the apache/pulsar-site repo later this week or early next week, unless
anyone has strong objections. I'll also update our release manager
documentation for the new process.

Thanks,
Michael

Re: [DISCUSS] Move all generated documentation to apache/pulsar-site repo

[Michael Marshall <mm...@apache.org>]

Thanks for the feedback, and thank you for sharing those docs Yu.

I will probably move forward on this task next week. First, I plan to
fix the doc generation in the pulsar-site repo.

Thanks,
Michael

On Fri, Jul 1, 2022 at 4:19 AM Yu <li...@apache.org> wrote:
>
> Hi Michael,
> Thanks for your awesome idea!
> You can request Lili (@urfree) and me to review after submitting PRs.
>
> Hi everyone,
> Before submitting changes to the Pulsar website and documentation, it's
> helpful to read Pulsar Documentation Organization Guide [1].
> It shows the comparison and relationship between the puslar/site2 repo [2]
> and puslar-site/site2 repo [3].
>
> [1]
> https://docs.google.com/document/d/1-1uJyd1k9_h56xiiVRVOnrLcCnTmg9n7SrHhNVNEEi4/edit#
> [2] https://github.com/apache/pulsar/tree/master/site2
> [3] https://github.com/apache/pulsar-site/tree/main/site2
>
> Yu and Lili
>
> On Thu, Jun 30, 2022 at 6:36 PM Enrico Olivelli <eo...@gmail.com> wrote:
>
> > +1
> > I like this idea.
> > We should not commit generated content to the code git repo
> >
> > Enrico
> >
> > Il giorno gio 30 giu 2022 alle ore 06:59 Michael Marshall
> > <mm...@apache.org> ha scritto:
> > >
> > > Hi Pulsar Community,
> > >
> > > I would like to discuss changing where our generated docs are stored.
> > >
> > > Currently, we keep some generated docs, like the python client docs
> > > and the swagger docs, in our apache/pulsar repo. There are other docs
> > > that are generated and stored in our apache/pulsar-site repo.
> > >
> > > I propose that we move all generated docs to be stored in the
> > > apache/pulsar-site repo. This change will primarily affect release
> > > managers since they will need to push commits to the pulsar-site repo.
> > > No one else should need to modify generated docs.
> > >
> > > My primary motivation is that I'd like to add new generated Javadoc
> > > pages for all of our recent releases so that we no longer only serve
> > > "-SNAPSHOT" versions of the generated docs. Those new docs will
> > > increase the size of our apache/pulsar repo. I prefer to keep the
> > > apache/pulsar repo small.
> > >
> > > I plan to open a PR to move these docs from the apache/pulsar repo to
> > > the apache/pulsar-site repo later this week or early next week, unless
> > > anyone has strong objections. I'll also update our release manager
> > > documentation for the new process.
> > >
> > > Thanks,
> > > Michael
> >

Re: [DISCUSS] Move all generated documentation to apache/pulsar-site repo

[Yu <li...@apache.org>]

Hi Michael,
Thanks for your awesome idea!
You can request Lili (@urfree) and me to review after submitting PRs.

Hi everyone,
Before submitting changes to the Pulsar website and documentation, it's
helpful to read Pulsar Documentation Organization Guide [1].
It shows the comparison and relationship between the puslar/site2 repo [2]
and puslar-site/site2 repo [3].

[1]
https://docs.google.com/document/d/1-1uJyd1k9_h56xiiVRVOnrLcCnTmg9n7SrHhNVNEEi4/edit#
[2] https://github.com/apache/pulsar/tree/master/site2
[3] https://github.com/apache/pulsar-site/tree/main/site2

Yu and Lili

On Thu, Jun 30, 2022 at 6:36 PM Enrico Olivelli <eo...@gmail.com> wrote:

> +1
> I like this idea.
> We should not commit generated content to the code git repo
>
> Enrico
>
> Il giorno gio 30 giu 2022 alle ore 06:59 Michael Marshall
> <mm...@apache.org> ha scritto:
> >
> > Hi Pulsar Community,
> >
> > I would like to discuss changing where our generated docs are stored.
> >
> > Currently, we keep some generated docs, like the python client docs
> > and the swagger docs, in our apache/pulsar repo. There are other docs
> > that are generated and stored in our apache/pulsar-site repo.
> >
> > I propose that we move all generated docs to be stored in the
> > apache/pulsar-site repo. This change will primarily affect release
> > managers since they will need to push commits to the pulsar-site repo.
> > No one else should need to modify generated docs.
> >
> > My primary motivation is that I'd like to add new generated Javadoc
> > pages for all of our recent releases so that we no longer only serve
> > "-SNAPSHOT" versions of the generated docs. Those new docs will
> > increase the size of our apache/pulsar repo. I prefer to keep the
> > apache/pulsar repo small.
> >
> > I plan to open a PR to move these docs from the apache/pulsar repo to
> > the apache/pulsar-site repo later this week or early next week, unless
> > anyone has strong objections. I'll also update our release manager
> > documentation for the new process.
> >
> > Thanks,
> > Michael
>

Re: [DISCUSS] Move all generated documentation to apache/pulsar-site repo

[Enrico Olivelli <eo...@gmail.com>]

+1
I like this idea.
We should not commit generated content to the code git repo

Enrico

Il giorno gio 30 giu 2022 alle ore 06:59 Michael Marshall
<mm...@apache.org> ha scritto:
>
> Hi Pulsar Community,
>
> I would like to discuss changing where our generated docs are stored.
>
> Currently, we keep some generated docs, like the python client docs
> and the swagger docs, in our apache/pulsar repo. There are other docs
> that are generated and stored in our apache/pulsar-site repo.
>
> I propose that we move all generated docs to be stored in the
> apache/pulsar-site repo. This change will primarily affect release
> managers since they will need to push commits to the pulsar-site repo.
> No one else should need to modify generated docs.
>
> My primary motivation is that I'd like to add new generated Javadoc
> pages for all of our recent releases so that we no longer only serve
> "-SNAPSHOT" versions of the generated docs. Those new docs will
> increase the size of our apache/pulsar repo. I prefer to keep the
> apache/pulsar repo small.
>
> I plan to open a PR to move these docs from the apache/pulsar repo to
> the apache/pulsar-site repo later this week or early next week, unless
> anyone has strong objections. I'll also update our release manager
> documentation for the new process.
>
> Thanks,
> Michael