ARROW-14738: [Python][Doc] Make return types clickable

Closes #11726 from amol-/ARROW-14738 Lead-authored-by: Alessandro Molina <amol@turbogears.org> Co-authored-by: Krisztián Szűcs <szucs.krisztian@gmail.com> Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com> Signed-off-by: Krisztián Szűcs <szucs.krisztian@gmail.com>
apache · Jan 19, 2022 · e9e16c9 · e9e16c9
1 parent fd580db
commit e9e16c9
Show file tree

Hide file tree

Showing 18 changed files with 186 additions and 107 deletions.
diff --git a/ci/conda_env_sphinx.txt b/ci/conda_env_sphinx.txt
@@ -19,8 +19,9 @@
 breathe
 doxygen
 ipython
-sphinx>=4.2
+numpydoc
 pydata-sphinx-theme
+sphinx>=4.2
 
 # Unable to install sphinx-tabs from conda-forge due to:
 # - package sphinx-tabs-1.2.1-py_0 requires sphinx >=2,<4, but none of the providers can be installed

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -61,17 +61,18 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'breathe',
+    'IPython.sphinxext.ipython_console_highlighting',
+    'IPython.sphinxext.ipython_directive',
+    'numpydoc',
+    'sphinx_tabs.tabs',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.ifconfig',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
-    'IPython.sphinxext.ipython_directive',
-    'IPython.sphinxext.ipython_console_highlighting',
-    'breathe',
-    'sphinx_tabs.tabs'
 ]
 
 # Show members for classes in .. autosummary
@@ -93,7 +94,35 @@
 ipython_mplbackend = ''
 
 # numpydoc configuration
-napoleon_use_rtype = False
+numpydoc_xref_param_type = True
+numpydoc_show_class_members = False
+numpydoc_xref_ignore = {
+    "or", "and", "of", "if", "default", "optional", "object",
+    "dicts", "rows", "Python", "source", "filesystem",
+    "dataset", "datasets",
+    # TODO those one could be linked to a glossary or python docs?
+    "file", "path", "paths", "mapping", "Mapping", "URI", "function",
+    "iterator", "Iterator",
+    # TODO this term is used regularly, but isn't actually exposed (base class)
+    "RecordBatchReader",
+    # additional ignores that could be fixed by rewriting the docstrings
+    "other", "supporting", "buffer", "protocol",  # from Codec / pa.compress
+    "depends", "on", "inputs",  # pyarrow.compute
+    "values", "coercible", "to", "arrays",  # pa.chunked_array, Table methods
+    "depending",  # to_pandas
+}
+numpydoc_xref_aliases = {
+    "array-like": ":func:`array-like <pyarrow.array>`",
+    "Array": "pyarrow.Array",
+    "Schema": "pyarrow.Schema",
+    "RecordBatch": "pyarrow.RecordBatch",
+    "Table": "pyarrow.Table",
+    "MemoryPool": "pyarrow.MemoryPool",
+    "NativeFile": "pyarrow.NativeFile",
+    "FileSystem": "pyarrow.fs.FileSystem",
+    "FileType": "pyarrow.fs.FileType",
+}
+
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -184,6 +213,12 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'pandas': ('https://pandas.pydata.org/docs/', None)
+}
+
 
 # -- Options for HTML output ----------------------------------------------
 

diff --git a/docs/source/developers/guide/step_by_step/building.rst b/docs/source/developers/guide/step_by_step/building.rst
@@ -84,7 +84,7 @@ documentation for any similar error advice. Also changing the CMake flags
 for compiling Arrow could be useful.
 
 CMake presets
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^
 
 You could also try to build with CMake presets which are a collection of
 build and test recipes for Arrow's CMake. They are a very useful
@@ -135,6 +135,7 @@ Building other Arrow libraries
       process.
 
       .. seealso::
+
          Follow the instructions to build PyArrow together with the C++ library
 
          - :ref:`build_pyarrow`

diff --git a/docs/source/python/api/dataset.rst b/docs/source/python/api/dataset.rst
@@ -51,6 +51,7 @@ Classes
    CsvFragmentScanOptions
    IpcFileFormat
    ParquetFileFormat
+   ParquetReadOptions
    ParquetFragmentScanOptions
    ORCFileFormat
    Partitioning
@@ -62,5 +63,7 @@ Classes
    FileSystemFactoryOptions
    FileSystemDatasetFactory
    UnionDataset
+   Fragment
+   FragmentScanOptions
    Scanner
    Expression
diff --git a/python/pyarrow/_csv.pyx b/python/pyarrow/_csv.pyx
@@ -493,7 +493,7 @@ cdef class ConvertOptions(_Weakrefable):
     ----------
     check_utf8 : bool, optional (default True)
         Whether to check UTF8 validity of string columns.
-    column_types : pa.Schema or dict, optional
+    column_types : pyarrow.Schema or dict, optional
         Explicitly map column names to column types. Passing this argument
         disables type inference on the defined columns.
     null_values : list, optional

diff --git a/python/pyarrow/_dataset.pyx b/python/pyarrow/_dataset.pyx
@@ -318,7 +318,7 @@ cdef class Dataset(_Weakrefable):
 
         Returns
         -------
-        table : Table instance
+        Table
         """
         return self.scanner(**kwargs).to_table()
 
@@ -329,7 +329,7 @@ cdef class Dataset(_Weakrefable):
 
         Returns
         -------
-        table : Table instance
+        Table
         """
         return self.scanner(**kwargs).take(indices)
 
@@ -340,7 +340,7 @@ cdef class Dataset(_Weakrefable):
 
         Returns
         -------
-        table : Table instance
+        Table
         """
         return self.scanner(**kwargs).head(num_rows)
 
@@ -578,7 +578,7 @@ cdef class FileSystemDataset(Dataset):
             ParquetFileFormat, IpcFileFormat, and CsvFileFormat are supported.
         filesystem : FileSystem
             The filesystem which files are from.
-        partitions : List[Expression], optional
+        partitions : list[Expression], optional
             Attach additional partition information for the file paths.
         root_partition : Expression, optional
             The top-level partition of the DataDataset.
@@ -886,7 +886,7 @@ cdef class Fragment(_Weakrefable):
 
         Returns
         -------
-        table : Table instance
+        Table
         """
         return self.scanner(**kwargs).take(indices)
 
@@ -897,7 +897,7 @@ cdef class Fragment(_Weakrefable):
 
         Returns
         -------
-        table : Table instance
+        Table
         """
         return self.scanner(**kwargs).head(num_rows)
 
@@ -1059,11 +1059,11 @@ cdef class CsvFileFormat(FileFormat):
 
     Parameters
     ----------
-    parse_options : csv.ParseOptions
+    parse_options : pyarrow.csv.ParseOptions
         Options regarding CSV parsing.
-    convert_options : csv.ConvertOptions
+    convert_options : pyarrow.csv.ConvertOptions
         Options regarding value conversion.
-    read_options : csv.ReadOptions
+    read_options : pyarrow.csv.ReadOptions
         General read options.
     default_fragment_scan_options : CsvFragmentScanOptions
         Default options for fragments scan.
@@ -1142,9 +1142,9 @@ cdef class CsvFragmentScanOptions(FragmentScanOptions):
 
     Parameters
     ----------
-    convert_options : csv.ConvertOptions
+    convert_options : pyarrow.csv.ConvertOptions
         Options regarding value conversion.
-    read_options : csv.ReadOptions
+    read_options : pyarrow.csv.ReadOptions
         General read options.
     """
 
@@ -1313,7 +1313,7 @@ cdef class DirectoryPartitioning(Partitioning):
     ----------
     schema : Schema
         The schema that describes the partitions present in the file path.
-    dictionaries : Dict[str, Array]
+    dictionaries : dict[str, Array]
         If the type of any field of `schema` is a dictionary type, the
         corresponding entry of `dictionaries` must be an array containing
         every value which may be taken by the corresponding column or an
@@ -1459,7 +1459,7 @@ cdef class HivePartitioning(Partitioning):
     ----------
     schema : Schema
         The schema that describes the partitions present in the file path.
-    dictionaries : Dict[str, Array]
+    dictionaries : dict[str, Array]
         If the type of any field of `schema` is a dictionary type, the
         corresponding entry of `dictionaries` must be an array containing
         every value which may be taken by the corresponding column or an
@@ -1802,7 +1802,7 @@ cdef class FileSystemDatasetFactory(DatasetFactory):
     ----------
     filesystem : pyarrow.fs.FileSystem
         Filesystem to discover.
-    paths_or_selector : pyarrow.fs.Selector or list of path-likes
+    paths_or_selector : pyarrow.fs.FileSelector or list of path-likes
         Either a Selector object or a list of path-like objects.
     format : FileFormat
         Currently only ParquetFileFormat and IpcFileFormat are supported.
@@ -2301,7 +2301,7 @@ cdef class Scanner(_Weakrefable):
 
         Returns
         -------
-        table : Table
+        Table
         """
         cdef CResult[shared_ptr[CTable]] result
 
@@ -2319,7 +2319,7 @@ cdef class Scanner(_Weakrefable):
 
         Returns
         -------
-        table : Table
+        Table
         """
         cdef CResult[shared_ptr[CTable]] result
         cdef shared_ptr[CArray] c_indices
@@ -2337,7 +2337,7 @@ cdef class Scanner(_Weakrefable):
 
         Returns
         -------
-        table : Table instance
+        Table
         """
         cdef CResult[shared_ptr[CTable]] result
         with nogil: