[Python] Add documentation about parquet.write_to_dataset and related methods

[asfimport]

pyarrow does not only allow one to write to a single Parquet file but you can also write only the schema metadata for a full multi-file dataset. This dataset can also be automatically partitioned by one or more columns. At the moment, this functionality is not really visible in the documentation. You mainly find the API documentation for it but we should have a small tutorial-like section that explains the differences and use cases for each of these functions.

See also https://stackoverflow.com/questions/47482434/can-pyarrow-write-multiple-parquet-files-to-a-folder-like-fastparquets-file-sch

Reporter: Wes McKinney / @wesm
Assignee: Donal Simmie / @dsimmie

PRs and other links:

• GitHub Pull Request #1925

_{Note: This issue was originally created as ARROW-1858. Please see the migration documentation for further details.}

[asfimport]

Wes McKinney / @wesm:
The lack of documentation about this came up in https://stackoverflow.com/questions/49085686/pyarrow-s3fs-partition-by-timetsamp

[asfimport]

Uwe Korn / @xhochy:
Issue resolved by pull request 1925
#1925

[asfimport]

ARF / @ARF1:
Even with the new documentation I am unclear on whether I can append to partitioned datasets.

I.e. is it possible to write a partitioned dataset when the entire dataset is too large to hold in memory prior to writing?