You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@arrow.apache.org by Wes McKinney <we...@gmail.com> on 2016/12/21 19:35:04 UTC
Documentation hosting
hi folks,
Our lack of organized documentation outside README documents on GitHub
is making it harder for people to pick up and use the project. What's
the easiest way to set up publishing tools that committers can access,
so we can add a /docs page on http://arrow.apache.org/, or links to
the specific Java/C++/Python documentation?
Uwe set up http://pyarrow.readthedocs.io/en/latest/, but it would be
better to have this hosted from the apache.org site. Let me know if
there are other ideas!
best
Wes
Re: Documentation hosting
Posted by Julien Le Dem <ju...@dremio.com>.
+1 too
Right now the site content is in https://github.com/apache/arrow-site
Thanks Uwe for volunteering!
On Tue, Jan 3, 2017 at 11:51 PM, Julian Hyde <jh...@apache.org> wrote:
> If you decide to take this approach, feel free to copy whatever you
> like from Calcite (not that you need my permission - this is ASL!) and
> please let me know if can help.
>
> On Tue, Jan 3, 2017 at 3:46 PM, Jason Altekruse <ja...@dremio.com> wrote:
> > +1
> >
> > Jason Altekruse
> > Software Engineer at Dremio
> > Apache Arrow Committer
> >
> > On Tue, Jan 3, 2017 at 2:59 PM, Leif Walsh <le...@gmail.com> wrote:
> >
> >> +1 this sounds pretty sane
> >> On Fri, Dec 30, 2016 at 06:02 Uwe L. Korn <uw...@xhochy.com> wrote:
> >>
> >> > I just had a look over the Apache Calcite approach and I like it very
> >> > much. Both, from a technical and the structural (i.e. keeping the
> >> > website in the main repo). This will enable us to have the format spec
> >> > on Github, let users edit the spec and the homepage via PRs and keep
> >> > them both linked and in sync. The following steps to do come to my
> mind:
> >> >
> >> > 1. Copy the infrastructure from Calcite
> >> > 2. Incorporate our current content into it (i.e. move the current
> >> > landing page into the structure)
> >> > 3. Either move the spec from "/format/" to "/site/format" or find a
> way
> >> > to let jekyll also parse this directory.
> >> > 4. Publish it after review.
> >> >
> >> > I would volunteer to do all this but would rather see some +1s before
> >> > proceeding ;)
> >> >
> >> > --
> >> > Uwe L. Korn
> >> > uwelk@xhochy.com
> >> >
> >> > On Wed, Dec 21, 2016, at 11:16 PM, Julian Hyde wrote:
> >> > > At Calcite we have a simple approach that Arrow could mimic. We keep
> >> our
> >> > > documentation under the source tree in .md (GitHub markdown) format
> and
> >> > > we use Jekyll to generate into the svn repo that backs the Apache
> web
> >> > > site. Due to the markdown format it’s easy for committers and
> >> > > non-committers to write documentation, they can test using a local
> >> Jekyll
> >> > > instance, non-committers can submit a pull request, and it’s not
> much
> >> > > effort for a committer to re-generate and commit the web site.
> >> > >
> >> > > You can also easily generate javadoc etc. into the same svn tree.
> >> > >
> >> > > Instructions here:
> >> > > https://github.com/apache/calcite/blob/master/site/README.md
> >> > > <https://github.com/apache/calcite/blob/master/site/README.md>
> >> > >
> >> > > Julian
> >> > >
> >> > >
> >> > > > On Dec 21, 2016, at 11:35 AM, Wes McKinney <we...@gmail.com>
> >> > wrote:
> >> > > >
> >> > > > hi folks,
> >> > > >
> >> > > > Our lack of organized documentation outside README documents on
> >> GitHub
> >> > > > is making it harder for people to pick up and use the project.
> What's
> >> > > > the easiest way to set up publishing tools that committers can
> >> access,
> >> > > > so we can add a /docs page on http://arrow.apache.org/, or links
> to
> >> > > > the specific Java/C++/Python documentation?
> >> > > >
> >> > > > Uwe set up http://pyarrow.readthedocs.io/en/latest/, but it
> would be
> >> > > > better to have this hosted from the apache.org site. Let me know
> if
> >> > > > there are other ideas!
> >> > > >
> >> > > > best
> >> > > > Wes
> >> > >
> >> >
> >> --
> >> --
> >> Cheers,
> >> Leif
> >>
>
--
Julien
Re: Documentation hosting
Posted by Julian Hyde <jh...@apache.org>.
If you decide to take this approach, feel free to copy whatever you
like from Calcite (not that you need my permission - this is ASL!) and
please let me know if can help.
On Tue, Jan 3, 2017 at 3:46 PM, Jason Altekruse <ja...@dremio.com> wrote:
> +1
>
> Jason Altekruse
> Software Engineer at Dremio
> Apache Arrow Committer
>
> On Tue, Jan 3, 2017 at 2:59 PM, Leif Walsh <le...@gmail.com> wrote:
>
>> +1 this sounds pretty sane
>> On Fri, Dec 30, 2016 at 06:02 Uwe L. Korn <uw...@xhochy.com> wrote:
>>
>> > I just had a look over the Apache Calcite approach and I like it very
>> > much. Both, from a technical and the structural (i.e. keeping the
>> > website in the main repo). This will enable us to have the format spec
>> > on Github, let users edit the spec and the homepage via PRs and keep
>> > them both linked and in sync. The following steps to do come to my mind:
>> >
>> > 1. Copy the infrastructure from Calcite
>> > 2. Incorporate our current content into it (i.e. move the current
>> > landing page into the structure)
>> > 3. Either move the spec from "/format/" to "/site/format" or find a way
>> > to let jekyll also parse this directory.
>> > 4. Publish it after review.
>> >
>> > I would volunteer to do all this but would rather see some +1s before
>> > proceeding ;)
>> >
>> > --
>> > Uwe L. Korn
>> > uwelk@xhochy.com
>> >
>> > On Wed, Dec 21, 2016, at 11:16 PM, Julian Hyde wrote:
>> > > At Calcite we have a simple approach that Arrow could mimic. We keep
>> our
>> > > documentation under the source tree in .md (GitHub markdown) format and
>> > > we use Jekyll to generate into the svn repo that backs the Apache web
>> > > site. Due to the markdown format it’s easy for committers and
>> > > non-committers to write documentation, they can test using a local
>> Jekyll
>> > > instance, non-committers can submit a pull request, and it’s not much
>> > > effort for a committer to re-generate and commit the web site.
>> > >
>> > > You can also easily generate javadoc etc. into the same svn tree.
>> > >
>> > > Instructions here:
>> > > https://github.com/apache/calcite/blob/master/site/README.md
>> > > <https://github.com/apache/calcite/blob/master/site/README.md>
>> > >
>> > > Julian
>> > >
>> > >
>> > > > On Dec 21, 2016, at 11:35 AM, Wes McKinney <we...@gmail.com>
>> > wrote:
>> > > >
>> > > > hi folks,
>> > > >
>> > > > Our lack of organized documentation outside README documents on
>> GitHub
>> > > > is making it harder for people to pick up and use the project. What's
>> > > > the easiest way to set up publishing tools that committers can
>> access,
>> > > > so we can add a /docs page on http://arrow.apache.org/, or links to
>> > > > the specific Java/C++/Python documentation?
>> > > >
>> > > > Uwe set up http://pyarrow.readthedocs.io/en/latest/, but it would be
>> > > > better to have this hosted from the apache.org site. Let me know if
>> > > > there are other ideas!
>> > > >
>> > > > best
>> > > > Wes
>> > >
>> >
>> --
>> --
>> Cheers,
>> Leif
>>
Re: Documentation hosting
Posted by Jason Altekruse <ja...@dremio.com>.
+1
Jason Altekruse
Software Engineer at Dremio
Apache Arrow Committer
On Tue, Jan 3, 2017 at 2:59 PM, Leif Walsh <le...@gmail.com> wrote:
> +1 this sounds pretty sane
> On Fri, Dec 30, 2016 at 06:02 Uwe L. Korn <uw...@xhochy.com> wrote:
>
> > I just had a look over the Apache Calcite approach and I like it very
> > much. Both, from a technical and the structural (i.e. keeping the
> > website in the main repo). This will enable us to have the format spec
> > on Github, let users edit the spec and the homepage via PRs and keep
> > them both linked and in sync. The following steps to do come to my mind:
> >
> > 1. Copy the infrastructure from Calcite
> > 2. Incorporate our current content into it (i.e. move the current
> > landing page into the structure)
> > 3. Either move the spec from "/format/" to "/site/format" or find a way
> > to let jekyll also parse this directory.
> > 4. Publish it after review.
> >
> > I would volunteer to do all this but would rather see some +1s before
> > proceeding ;)
> >
> > --
> > Uwe L. Korn
> > uwelk@xhochy.com
> >
> > On Wed, Dec 21, 2016, at 11:16 PM, Julian Hyde wrote:
> > > At Calcite we have a simple approach that Arrow could mimic. We keep
> our
> > > documentation under the source tree in .md (GitHub markdown) format and
> > > we use Jekyll to generate into the svn repo that backs the Apache web
> > > site. Due to the markdown format it’s easy for committers and
> > > non-committers to write documentation, they can test using a local
> Jekyll
> > > instance, non-committers can submit a pull request, and it’s not much
> > > effort for a committer to re-generate and commit the web site.
> > >
> > > You can also easily generate javadoc etc. into the same svn tree.
> > >
> > > Instructions here:
> > > https://github.com/apache/calcite/blob/master/site/README.md
> > > <https://github.com/apache/calcite/blob/master/site/README.md>
> > >
> > > Julian
> > >
> > >
> > > > On Dec 21, 2016, at 11:35 AM, Wes McKinney <we...@gmail.com>
> > wrote:
> > > >
> > > > hi folks,
> > > >
> > > > Our lack of organized documentation outside README documents on
> GitHub
> > > > is making it harder for people to pick up and use the project. What's
> > > > the easiest way to set up publishing tools that committers can
> access,
> > > > so we can add a /docs page on http://arrow.apache.org/, or links to
> > > > the specific Java/C++/Python documentation?
> > > >
> > > > Uwe set up http://pyarrow.readthedocs.io/en/latest/, but it would be
> > > > better to have this hosted from the apache.org site. Let me know if
> > > > there are other ideas!
> > > >
> > > > best
> > > > Wes
> > >
> >
> --
> --
> Cheers,
> Leif
>
Re: Documentation hosting
Posted by Leif Walsh <le...@gmail.com>.
+1 this sounds pretty sane
On Fri, Dec 30, 2016 at 06:02 Uwe L. Korn <uw...@xhochy.com> wrote:
> I just had a look over the Apache Calcite approach and I like it very
> much. Both, from a technical and the structural (i.e. keeping the
> website in the main repo). This will enable us to have the format spec
> on Github, let users edit the spec and the homepage via PRs and keep
> them both linked and in sync. The following steps to do come to my mind:
>
> 1. Copy the infrastructure from Calcite
> 2. Incorporate our current content into it (i.e. move the current
> landing page into the structure)
> 3. Either move the spec from "/format/" to "/site/format" or find a way
> to let jekyll also parse this directory.
> 4. Publish it after review.
>
> I would volunteer to do all this but would rather see some +1s before
> proceeding ;)
>
> --
> Uwe L. Korn
> uwelk@xhochy.com
>
> On Wed, Dec 21, 2016, at 11:16 PM, Julian Hyde wrote:
> > At Calcite we have a simple approach that Arrow could mimic. We keep our
> > documentation under the source tree in .md (GitHub markdown) format and
> > we use Jekyll to generate into the svn repo that backs the Apache web
> > site. Due to the markdown format it’s easy for committers and
> > non-committers to write documentation, they can test using a local Jekyll
> > instance, non-committers can submit a pull request, and it’s not much
> > effort for a committer to re-generate and commit the web site.
> >
> > You can also easily generate javadoc etc. into the same svn tree.
> >
> > Instructions here:
> > https://github.com/apache/calcite/blob/master/site/README.md
> > <https://github.com/apache/calcite/blob/master/site/README.md>
> >
> > Julian
> >
> >
> > > On Dec 21, 2016, at 11:35 AM, Wes McKinney <we...@gmail.com>
> wrote:
> > >
> > > hi folks,
> > >
> > > Our lack of organized documentation outside README documents on GitHub
> > > is making it harder for people to pick up and use the project. What's
> > > the easiest way to set up publishing tools that committers can access,
> > > so we can add a /docs page on http://arrow.apache.org/, or links to
> > > the specific Java/C++/Python documentation?
> > >
> > > Uwe set up http://pyarrow.readthedocs.io/en/latest/, but it would be
> > > better to have this hosted from the apache.org site. Let me know if
> > > there are other ideas!
> > >
> > > best
> > > Wes
> >
>
--
--
Cheers,
Leif
Re: Documentation hosting
Posted by "Uwe L. Korn" <uw...@xhochy.com>.
I just had a look over the Apache Calcite approach and I like it very
much. Both, from a technical and the structural (i.e. keeping the
website in the main repo). This will enable us to have the format spec
on Github, let users edit the spec and the homepage via PRs and keep
them both linked and in sync. The following steps to do come to my mind:
1. Copy the infrastructure from Calcite
2. Incorporate our current content into it (i.e. move the current
landing page into the structure)
3. Either move the spec from "/format/" to "/site/format" or find a way
to let jekyll also parse this directory.
4. Publish it after review.
I would volunteer to do all this but would rather see some +1s before
proceeding ;)
--
Uwe L. Korn
uwelk@xhochy.com
On Wed, Dec 21, 2016, at 11:16 PM, Julian Hyde wrote:
> At Calcite we have a simple approach that Arrow could mimic. We keep our
> documentation under the source tree in .md (GitHub markdown) format and
> we use Jekyll to generate into the svn repo that backs the Apache web
> site. Due to the markdown format it’s easy for committers and
> non-committers to write documentation, they can test using a local Jekyll
> instance, non-committers can submit a pull request, and it’s not much
> effort for a committer to re-generate and commit the web site.
>
> You can also easily generate javadoc etc. into the same svn tree.
>
> Instructions here:
> https://github.com/apache/calcite/blob/master/site/README.md
> <https://github.com/apache/calcite/blob/master/site/README.md>
>
> Julian
>
>
> > On Dec 21, 2016, at 11:35 AM, Wes McKinney <we...@gmail.com> wrote:
> >
> > hi folks,
> >
> > Our lack of organized documentation outside README documents on GitHub
> > is making it harder for people to pick up and use the project. What's
> > the easiest way to set up publishing tools that committers can access,
> > so we can add a /docs page on http://arrow.apache.org/, or links to
> > the specific Java/C++/Python documentation?
> >
> > Uwe set up http://pyarrow.readthedocs.io/en/latest/, but it would be
> > better to have this hosted from the apache.org site. Let me know if
> > there are other ideas!
> >
> > best
> > Wes
>
Re: Documentation hosting
Posted by Julian Hyde <jh...@apache.org>.
At Calcite we have a simple approach that Arrow could mimic. We keep our documentation under the source tree in .md (GitHub markdown) format and we use Jekyll to generate into the svn repo that backs the Apache web site. Due to the markdown format it’s easy for committers and non-committers to write documentation, they can test using a local Jekyll instance, non-committers can submit a pull request, and it’s not much effort for a committer to re-generate and commit the web site.
You can also easily generate javadoc etc. into the same svn tree.
Instructions here: https://github.com/apache/calcite/blob/master/site/README.md <https://github.com/apache/calcite/blob/master/site/README.md>
Julian
> On Dec 21, 2016, at 11:35 AM, Wes McKinney <we...@gmail.com> wrote:
>
> hi folks,
>
> Our lack of organized documentation outside README documents on GitHub
> is making it harder for people to pick up and use the project. What's
> the easiest way to set up publishing tools that committers can access,
> so we can add a /docs page on http://arrow.apache.org/, or links to
> the specific Java/C++/Python documentation?
>
> Uwe set up http://pyarrow.readthedocs.io/en/latest/, but it would be
> better to have this hosted from the apache.org site. Let me know if
> there are other ideas!
>
> best
> Wes