ARROW-3620: [Python] Document pa.cpu_count() in Sphinx API docs

docs/source/python/api.rst

@@ -282,21 +282,8 @@ Serialization and IPC
    SerializedPyObject
    SerializationContext
 
-.. _api.feather:
-
-Feather Format
-~~~~~~~~~~~~~~
-
-.. currentmodule:: pyarrow.feather
-
 .. _api.memory_pool:
 
-.. autosummary::
-   :toctree: generated/
-
-   read_feather
-   write_feather
-
 Memory Pools
 ------------
 
@@ -329,8 +316,8 @@ Type Classes
 
 .. _api.plasma:
 
-In-Memory Object Store
-----------------------
+Plasma In-Memory Object Store
+-----------------------------
 
 .. autosummary::
    :toctree: generated/
@@ -354,12 +341,27 @@ CSV Files
    ConvertOptions
    read_csv
 
-.. currentmodule:: pyarrow.parquet
+.. _api.feather:
+
+Feather Files
+-------------
+
+.. currentmodule:: pyarrow.feather
+
+.. autosummary::
+   :toctree: generated/
+
+   read_feather
+   write_feather
+
+.. currentmodule:: pyarrow
 
 .. _api.parquet:
 
-Apache Parquet
---------------
+Parquet Files
+-------------
+
+.. currentmodule:: pyarrow.parquet
 
 .. autosummary::
    :toctree: generated/
@@ -377,6 +379,15 @@ Apache Parquet
 
 .. currentmodule:: pyarrow
 
+Multi-Threading
+---------------
+
+.. autosummary::
+   :toctree: generated/
+
+   cpu_count
+   set_cpu_count
+
 Using with C extensions
 -----------------------
 

docs/source/python/csv.rst

@@ -86,3 +86,7 @@ overhead of reading CSV files.
 Performance options can be controlled through the :class:`ReadOptions` class.
 Multi-threaded reading is the default for highest performance, distributing
 the workload efficiently over all available cores.
+
+.. note::
+   The number of threads to use concurrently is automatically inferred by Arrow
+   and can be inspected using the :func:`~pyarrow.cpu_count()` function.

python/pyarrow/lib.pyx

@@ -42,9 +42,10 @@ def cpu_count():
     Return the number of threads to use in parallel operations.
 
     The number of threads is determined at startup by inspecting the
-    OMP_NUM_THREADS and OMP_THREAD_LIMIT environment variables.  If neither
-    is present, it will default to the number of hardware threads on the
-    system.  It can be modified at runtime by calling set_cpu_count().
+    ``OMP_NUM_THREADS`` and ``OMP_THREAD_LIMIT`` environment variables.
+    If neither is present, it will default to the number of hardware threads
+    on the system.  It can be modified at runtime by calling
+    :func:`set_cpu_count()`.
     """
     return GetCpuThreadPoolCapacity()