[
https://issues.apache.org/jira/browse/ARROW-2684?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16506519#comment-16506519
]
Dominik Moritz commented on ARROW-2684:
---------------------------------------
Here are some concrete suggestions
* Instead of using ipython with noise (`In [9]:`), write small, reusable, code
snippets
* Describe what the different kinds of NativeFile mean and when to use them.
The description of Buffer (arrow::Buffer can be zero-copy sliced to permit
Buffers to cheaply reference other Buffers, while preserving memory lifetime
and clean parent-child relationships) is a bit cryptic to beginners.
* Describe concrete use cases like: taking a pandas data frame and write a
file to disk, load an arrow file from disk to a pandas data frame, and read and
write to a memory mapped files to exchange data between applications.
* Overall, the examples are not practical because for example in
[https://arrow.apache.org/docs/python/ipc.html#writing-and-reading-random-access-files]
it is not clear what to do with the sink (the BufferOutputStream).
* Remove the feather documentation if that is not the preferred way to write
files anymore.
* Why do we write the same batch 5 time? `for i in range(5): ...:
writer.write_batch(batch)`
I don't know how to break this up into multiple issues because I'm not familiar
enough with arrow (started using it yesterday) but I hope that these are
helpful suggestions.
> Improve Python documentation
> ----------------------------
>
> Key: ARROW-2684
> URL: https://issues.apache.org/jira/browse/ARROW-2684
> Project: Apache Arrow
> Issue Type: Improvement
> Components: Python
> Reporter: Dominik Moritz
> Priority: Major
>
> The python documentation is currently not beginner friendly and things like
> the IPC format are not discoverable. For example,
> [https://arrow.apache.org/docs/python/ipc.html] has the word "IPC" only in
> the title. Also, it's currently not clear how to write a file to disk.
> I propose that the documentation becomes more of an API docs rather than a
> set of examples. Examples are valuable but they cannot replace documentation
> of the inputs and outputs of various functions.
> See [https://github.com/apache/arrow/issues/2119] for more.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
