You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@arrow.apache.org by Uwe Korn <uw...@xhochy.com> on 2016/05/07 16:44:50 UTC
Documentation for Apache Arrow
Hello,
as Arrow grows and we want to improve usage/adoption, we definitely need
to start documenting it a bit. I would volunteer to work on writing some
sections, but first we need to agree on the used tools. I would suggest
the following setup:
* central Arrow documentation (i.e. the layout, IPC design, other
language independent stuff) could be written in asciidoc or markdown
* Language specific documentation, mainly API documentation,
installation how-tos and some basic usage (should link to the
central documentation as much as possible instead of copying content).
o Python with Sphinx and sphinx-apidoc
o C++ with doxygen
o Java with whatever currently the standard in the Java world is :)
Please let me know if you feel comfortable with this structure and what
tools are preferred.
Cheers
Uwe
Re: Documentation for Apache Arrow
Posted by Jacques Nadeau <ja...@apache.org>.
The stuff we use on Drill can be found here:
https://github.com/apache/drill/tree/gh-pages
It is simple and works pretty well. I like markdown's simplicity.
I feel like Todd had some substantial thoughts on this earlier (and chose
something over markdown for Kudu).
On Sun, May 8, 2016 at 5:07 PM, Wes McKinney <we...@gmail.com> wrote:
> For the central documentation I'm more in favor of asciidoc for its
> seemingly stronger support of interconnected documents (for example,
> O'Reilly has moved most of its authoring work to asciidoc from Docbook
> XML). But there may be resources for Markdown that I'm not familiar
> with. There are multiple static site generators that use Markdown (I
> have experience with Pelican).
>
> Can someone point me to the source repo for Apache Drill's
> documentation (it is written in Markdown?)? Any other ways we can help
> make a decision on this?
>
> - Wes
>
> On Sun, May 8, 2016 at 10:36 AM, Jacques Nadeau <ja...@apache.org>
> wrote:
> > Sounds good. Javadoc is the tool for Java. :)
> >
> > On Sat, May 7, 2016 at 9:44 AM, Uwe Korn <uw...@xhochy.com> wrote:
> >
> >> Hello,
> >>
> >> as Arrow grows and we want to improve usage/adoption, we definitely need
> >> to start documenting it a bit. I would volunteer to work on writing some
> >> sections, but first we need to agree on the used tools. I would suggest
> the
> >> following setup:
> >>
> >> * central Arrow documentation (i.e. the layout, IPC design, other
> >> language independent stuff) could be written in asciidoc or markdown
> >> * Language specific documentation, mainly API documentation,
> >> installation how-tos and some basic usage (should link to the
> >> central documentation as much as possible instead of copying
> content).
> >> o Python with Sphinx and sphinx-apidoc
> >> o C++ with doxygen
> >> o Java with whatever currently the standard in the Java world is :)
> >>
> >> Please let me know if you feel comfortable with this structure and what
> >> tools are preferred.
> >>
> >> Cheers
> >>
> >> Uwe
> >>
> >>
>
Re: Documentation for Apache Arrow
Posted by Wes McKinney <we...@gmail.com>.
For the central documentation I'm more in favor of asciidoc for its
seemingly stronger support of interconnected documents (for example,
O'Reilly has moved most of its authoring work to asciidoc from Docbook
XML). But there may be resources for Markdown that I'm not familiar
with. There are multiple static site generators that use Markdown (I
have experience with Pelican).
Can someone point me to the source repo for Apache Drill's
documentation (it is written in Markdown?)? Any other ways we can help
make a decision on this?
- Wes
On Sun, May 8, 2016 at 10:36 AM, Jacques Nadeau <ja...@apache.org> wrote:
> Sounds good. Javadoc is the tool for Java. :)
>
> On Sat, May 7, 2016 at 9:44 AM, Uwe Korn <uw...@xhochy.com> wrote:
>
>> Hello,
>>
>> as Arrow grows and we want to improve usage/adoption, we definitely need
>> to start documenting it a bit. I would volunteer to work on writing some
>> sections, but first we need to agree on the used tools. I would suggest the
>> following setup:
>>
>> * central Arrow documentation (i.e. the layout, IPC design, other
>> language independent stuff) could be written in asciidoc or markdown
>> * Language specific documentation, mainly API documentation,
>> installation how-tos and some basic usage (should link to the
>> central documentation as much as possible instead of copying content).
>> o Python with Sphinx and sphinx-apidoc
>> o C++ with doxygen
>> o Java with whatever currently the standard in the Java world is :)
>>
>> Please let me know if you feel comfortable with this structure and what
>> tools are preferred.
>>
>> Cheers
>>
>> Uwe
>>
>>
Re: Documentation for Apache Arrow
Posted by Jacques Nadeau <ja...@apache.org>.
Sounds good. Javadoc is the tool for Java. :)
On Sat, May 7, 2016 at 9:44 AM, Uwe Korn <uw...@xhochy.com> wrote:
> Hello,
>
> as Arrow grows and we want to improve usage/adoption, we definitely need
> to start documenting it a bit. I would volunteer to work on writing some
> sections, but first we need to agree on the used tools. I would suggest the
> following setup:
>
> * central Arrow documentation (i.e. the layout, IPC design, other
> language independent stuff) could be written in asciidoc or markdown
> * Language specific documentation, mainly API documentation,
> installation how-tos and some basic usage (should link to the
> central documentation as much as possible instead of copying content).
> o Python with Sphinx and sphinx-apidoc
> o C++ with doxygen
> o Java with whatever currently the standard in the Java world is :)
>
> Please let me know if you feel comfortable with this structure and what
> tools are preferred.
>
> Cheers
>
> Uwe
>
>