You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@avro.apache.org by Martin Grigorov <mg...@apache.org> on 2022/12/08 09:53:26 UTC
Deploy documentation via .asf.yaml
Hello,
I'd like to propose changing the way the site/documentation is deployed at
https://avro.apache.org.
Currently it comes from Subversion:
http://svn-master.apache.org/repos/asf/avro/site/publish
I suggest to make use of .asf.yaml (
https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features#Git.asf.yamlfeatures-WebsitedeploymentserviceforGitrepositories)
instead.
Recently I helped Apache Arrow team to deploy the documentation of
DataFusion Python subproject via .asf.yaml and I gained some knowledge how
it works - https://github.com/apache/arrow-datafusion-python/pull/104.
With the new approach it will be possible to:
1) deploy the docs from master to https://avro.staged.apache.org
2) deploy latest release, e.g. 1.11.1, to https://avro.apache.org
3) deploy older versions, e.g. 1.10.0, to https://avro.apache.org/1.10.0/
If the team likes the idea I will work on a PR!
For pre-Hugo versions, i.e. the Forrest based ones, I will need Ryan's (or
anyone who knows how it works) help to do it!
Regards,
Martin
Re: Deploy documentation via .asf.yaml
Posted by Ryan Skraba <ry...@skraba.com>.
Hello! I came to the same conclusion about splitting the content
(with AVRO-3651). Anything outside a release (like the community
pages) can be published at any time.
Anything inside a release (like the spec and API docs) should be
released with the binary artifacts. This is something to address if
we were to release SDKs separately.
Is it possible to use a different branch in the avro repo for the main website?
I'm so glad you're taking a look at this! All my best, Ryan
On Wed, Jan 4, 2023 at 1:47 PM Martin Grigorov <mg...@apache.org> wrote:
>
> Status update:
>
> https://github.com/apache/avro/compare/master...avro-3686-asf.yaml-docs?expand=1
> With the new docs.yaml Github Actions workflow we can deploy the docs per
> version at /docs/1.12.0-SNAPSHOT, /docs/1.11.1-SNAPSHOT, /docs/1.12.0, etc.
> whenever we push to master, branch-1.11 or a (release) tag.
>
> For example see https://avro.apache.org/docs-new/1.12.0-SNAPSHOT
>
> The next problem is that we may need to split the site in two parts:
> 1) non-versioned content like "Project", "Blog", "Community", "ASF Links",
> etc.
> 2) versioned content - the documentation
>
> My idea is to move the non-versioned content to
> https://github.com/apache/avro-site (a new Git repo) and leave only the
> versioned content in apache/avro#doc folder.
> Any objections ? Or better ideas ?
>
> On Fri, Dec 9, 2022 at 4:29 PM Martin Grigorov <mg...@apache.org> wrote:
>
> > I created https://issues.apache.org/jira/browse/AVRO-3686
> >
> > AVRO-3651 can easily be solved by using https://avro.a.o for
> > current/master instead of https://avro.staged.a.o.
> > With the current pace of editing the docs (close to none) I think this
> > won't be a problem for the users.
> >
> > Martin
> >
> > On Thu, Dec 8, 2022 at 7:47 PM Ryan Skraba <ry...@skraba.com> wrote:
> >
> >> Oh yes!!! This would be an excellent change -- I was looking at the
> >> "nightlies.apache.org" used by Flink, but I think the staged approach
> >> is really nice.
> >>
> >> Have you taken a look at AVRO-3651 [1]? I was thinking this approach
> >> would make it possible to link to the "release" website artifacts, but
> >> have the "Edit this page" links point to a current branch version on
> >> github.
> >>
> >> I never want to build with Forrest again; that ship has sailed! But
> >> we can reuse the existing artifacts for builds before 1.11.1, and only
> >> auto-deploy hugo builds.
> >>
> >> I think the new website is a great start, having a better build and
> >> deploy would definitely help us make it better! I'm interested in
> >> learning too ;)
> >>
> >> All my best, Ryan
> >>
> >> [1]: https://issues.apache.org/jira/browse/AVRO-3651
> >>
> >> On Thu, Dec 8, 2022 at 10:54 AM Martin Grigorov <mg...@apache.org>
> >> wrote:
> >> >
> >> > Hello,
> >> >
> >> > I'd like to propose changing the way the site/documentation is deployed
> >> at
> >> > https://avro.apache.org.
> >> > Currently it comes from Subversion:
> >> > http://svn-master.apache.org/repos/asf/avro/site/publish
> >> > I suggest to make use of .asf.yaml (
> >> >
> >> https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features#Git.asf.yamlfeatures-WebsitedeploymentserviceforGitrepositories
> >> )
> >> > instead.
> >> >
> >> > Recently I helped Apache Arrow team to deploy the documentation of
> >> > DataFusion Python subproject via .asf.yaml and I gained some knowledge
> >> how
> >> > it works - https://github.com/apache/arrow-datafusion-python/pull/104.
> >> >
> >> > With the new approach it will be possible to:
> >> > 1) deploy the docs from master to https://avro.staged.apache.org
> >> > 2) deploy latest release, e.g. 1.11.1, to https://avro.apache.org
> >> > 3) deploy older versions, e.g. 1.10.0, to
> >> https://avro.apache.org/1.10.0/
> >> >
> >> > If the team likes the idea I will work on a PR!
> >> >
> >> > For pre-Hugo versions, i.e. the Forrest based ones, I will need Ryan's
> >> (or
> >> > anyone who knows how it works) help to do it!
> >> >
> >> > Regards,
> >> > Martin
> >>
> >
Re: Deploy documentation via .asf.yaml
Posted by Martin Grigorov <mg...@apache.org>.
Status update:
https://github.com/apache/avro/compare/master...avro-3686-asf.yaml-docs?expand=1
With the new docs.yaml Github Actions workflow we can deploy the docs per
version at /docs/1.12.0-SNAPSHOT, /docs/1.11.1-SNAPSHOT, /docs/1.12.0, etc.
whenever we push to master, branch-1.11 or a (release) tag.
For example see https://avro.apache.org/docs-new/1.12.0-SNAPSHOT
The next problem is that we may need to split the site in two parts:
1) non-versioned content like "Project", "Blog", "Community", "ASF Links",
etc.
2) versioned content - the documentation
My idea is to move the non-versioned content to
https://github.com/apache/avro-site (a new Git repo) and leave only the
versioned content in apache/avro#doc folder.
Any objections ? Or better ideas ?
On Fri, Dec 9, 2022 at 4:29 PM Martin Grigorov <mg...@apache.org> wrote:
> I created https://issues.apache.org/jira/browse/AVRO-3686
>
> AVRO-3651 can easily be solved by using https://avro.a.o for
> current/master instead of https://avro.staged.a.o.
> With the current pace of editing the docs (close to none) I think this
> won't be a problem for the users.
>
> Martin
>
> On Thu, Dec 8, 2022 at 7:47 PM Ryan Skraba <ry...@skraba.com> wrote:
>
>> Oh yes!!! This would be an excellent change -- I was looking at the
>> "nightlies.apache.org" used by Flink, but I think the staged approach
>> is really nice.
>>
>> Have you taken a look at AVRO-3651 [1]? I was thinking this approach
>> would make it possible to link to the "release" website artifacts, but
>> have the "Edit this page" links point to a current branch version on
>> github.
>>
>> I never want to build with Forrest again; that ship has sailed! But
>> we can reuse the existing artifacts for builds before 1.11.1, and only
>> auto-deploy hugo builds.
>>
>> I think the new website is a great start, having a better build and
>> deploy would definitely help us make it better! I'm interested in
>> learning too ;)
>>
>> All my best, Ryan
>>
>> [1]: https://issues.apache.org/jira/browse/AVRO-3651
>>
>> On Thu, Dec 8, 2022 at 10:54 AM Martin Grigorov <mg...@apache.org>
>> wrote:
>> >
>> > Hello,
>> >
>> > I'd like to propose changing the way the site/documentation is deployed
>> at
>> > https://avro.apache.org.
>> > Currently it comes from Subversion:
>> > http://svn-master.apache.org/repos/asf/avro/site/publish
>> > I suggest to make use of .asf.yaml (
>> >
>> https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features#Git.asf.yamlfeatures-WebsitedeploymentserviceforGitrepositories
>> )
>> > instead.
>> >
>> > Recently I helped Apache Arrow team to deploy the documentation of
>> > DataFusion Python subproject via .asf.yaml and I gained some knowledge
>> how
>> > it works - https://github.com/apache/arrow-datafusion-python/pull/104.
>> >
>> > With the new approach it will be possible to:
>> > 1) deploy the docs from master to https://avro.staged.apache.org
>> > 2) deploy latest release, e.g. 1.11.1, to https://avro.apache.org
>> > 3) deploy older versions, e.g. 1.10.0, to
>> https://avro.apache.org/1.10.0/
>> >
>> > If the team likes the idea I will work on a PR!
>> >
>> > For pre-Hugo versions, i.e. the Forrest based ones, I will need Ryan's
>> (or
>> > anyone who knows how it works) help to do it!
>> >
>> > Regards,
>> > Martin
>>
>
Re: Deploy documentation via .asf.yaml
Posted by Martin Grigorov <mg...@apache.org>.
I created https://issues.apache.org/jira/browse/AVRO-3686
AVRO-3651 can easily be solved by using https://avro.a.o for current/master
instead of https://avro.staged.a.o.
With the current pace of editing the docs (close to none) I think this
won't be a problem for the users.
Martin
On Thu, Dec 8, 2022 at 7:47 PM Ryan Skraba <ry...@skraba.com> wrote:
> Oh yes!!! This would be an excellent change -- I was looking at the
> "nightlies.apache.org" used by Flink, but I think the staged approach
> is really nice.
>
> Have you taken a look at AVRO-3651 [1]? I was thinking this approach
> would make it possible to link to the "release" website artifacts, but
> have the "Edit this page" links point to a current branch version on
> github.
>
> I never want to build with Forrest again; that ship has sailed! But
> we can reuse the existing artifacts for builds before 1.11.1, and only
> auto-deploy hugo builds.
>
> I think the new website is a great start, having a better build and
> deploy would definitely help us make it better! I'm interested in
> learning too ;)
>
> All my best, Ryan
>
> [1]: https://issues.apache.org/jira/browse/AVRO-3651
>
> On Thu, Dec 8, 2022 at 10:54 AM Martin Grigorov <mg...@apache.org>
> wrote:
> >
> > Hello,
> >
> > I'd like to propose changing the way the site/documentation is deployed
> at
> > https://avro.apache.org.
> > Currently it comes from Subversion:
> > http://svn-master.apache.org/repos/asf/avro/site/publish
> > I suggest to make use of .asf.yaml (
> >
> https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features#Git.asf.yamlfeatures-WebsitedeploymentserviceforGitrepositories
> )
> > instead.
> >
> > Recently I helped Apache Arrow team to deploy the documentation of
> > DataFusion Python subproject via .asf.yaml and I gained some knowledge
> how
> > it works - https://github.com/apache/arrow-datafusion-python/pull/104.
> >
> > With the new approach it will be possible to:
> > 1) deploy the docs from master to https://avro.staged.apache.org
> > 2) deploy latest release, e.g. 1.11.1, to https://avro.apache.org
> > 3) deploy older versions, e.g. 1.10.0, to
> https://avro.apache.org/1.10.0/
> >
> > If the team likes the idea I will work on a PR!
> >
> > For pre-Hugo versions, i.e. the Forrest based ones, I will need Ryan's
> (or
> > anyone who knows how it works) help to do it!
> >
> > Regards,
> > Martin
>
Re: Deploy documentation via .asf.yaml
Posted by Ryan Skraba <ry...@skraba.com>.
Oh yes!!! This would be an excellent change -- I was looking at the
"nightlies.apache.org" used by Flink, but I think the staged approach
is really nice.
Have you taken a look at AVRO-3651 [1]? I was thinking this approach
would make it possible to link to the "release" website artifacts, but
have the "Edit this page" links point to a current branch version on
github.
I never want to build with Forrest again; that ship has sailed! But
we can reuse the existing artifacts for builds before 1.11.1, and only
auto-deploy hugo builds.
I think the new website is a great start, having a better build and
deploy would definitely help us make it better! I'm interested in
learning too ;)
All my best, Ryan
[1]: https://issues.apache.org/jira/browse/AVRO-3651
On Thu, Dec 8, 2022 at 10:54 AM Martin Grigorov <mg...@apache.org> wrote:
>
> Hello,
>
> I'd like to propose changing the way the site/documentation is deployed at
> https://avro.apache.org.
> Currently it comes from Subversion:
> http://svn-master.apache.org/repos/asf/avro/site/publish
> I suggest to make use of .asf.yaml (
> https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features#Git.asf.yamlfeatures-WebsitedeploymentserviceforGitrepositories)
> instead.
>
> Recently I helped Apache Arrow team to deploy the documentation of
> DataFusion Python subproject via .asf.yaml and I gained some knowledge how
> it works - https://github.com/apache/arrow-datafusion-python/pull/104.
>
> With the new approach it will be possible to:
> 1) deploy the docs from master to https://avro.staged.apache.org
> 2) deploy latest release, e.g. 1.11.1, to https://avro.apache.org
> 3) deploy older versions, e.g. 1.10.0, to https://avro.apache.org/1.10.0/
>
> If the team likes the idea I will work on a PR!
>
> For pre-Hugo versions, i.e. the Forrest based ones, I will need Ryan's (or
> anyone who knows how it works) help to do it!
>
> Regards,
> Martin