ARROW-16994: [Docs][CI] Clean up docs warnings (apache#13533)

lidavidm · web-flow · commit 7922ed0d942e · 2022-07-07T09:16:29.000-04:00
Authored-by: David Li &lt;li.davidm96@gmail.com&gt;
Signed-off-by: David Li &lt;li.davidm96@gmail.com&gt;
diff --git a/.github/workflows/docs_light.yml b/.github/workflows/docs_light.yml
@@ -40,7 +40,7 @@ jobs:
     name: AMD64 Conda Python 3.9 Sphinx Documentation
     runs-on: ubuntu-latest
     if: ${{ !contains(github.event.pull_request.title, 'WIP') }}
-    timeout-minutes: 30
+    timeout-minutes: 45
     env:
       PYTHON: "3.9"
     steps:
diff --git a/docs/source/cpp/api/compute.rst b/docs/source/cpp/api/compute.rst
@@ -73,9 +73,6 @@ Streaming Execution Operators
 Execution Plan Expressions
 --------------------------
 
-.. doxygenclass:: arrow::FieldRef
-   :members:
-
 .. doxygengroup:: expression-core
    :content-only:
    :members:
diff --git a/docs/source/cpp/api/datatype.rst b/docs/source/cpp/api/datatype.rst
@@ -106,9 +106,11 @@ Helpers for looking up fields
 
 .. doxygenclass:: arrow::FieldPath
    :members:
+   :undoc-members:
 
 .. doxygenclass:: arrow::FieldRef
    :members:
+   :undoc-members:
 
 
 Utilities
diff --git a/docs/source/cpp/api/flight.rst b/docs/source/cpp/api/flight.rst
@@ -204,5 +204,5 @@ error codes.
 Implementing Custom Transports
 ==============================
 
-.. doxygenfile:: arrow/flight/transport_impl.h
+.. doxygenfile:: arrow/flight/transport.h
    :sections: briefdescription detaileddescription
diff --git a/docs/source/cpp/api/support.rst b/docs/source/cpp/api/support.rst
@@ -76,7 +76,7 @@ introduced API).
 Runtime Configuration
 =====================
 
-.. doxygenstruct:: arrow::ArrowGlobalOptions
+.. doxygenstruct:: arrow::GlobalOptions
    :members:
 
 
diff --git a/docs/source/cpp/build_system.rst b/docs/source/cpp/build_system.rst
@@ -183,6 +183,6 @@ XML. To download, you can use the following batch script:
 By default, the timezone database will be detected at ``%USERPROFILE%\Downloads\tzdata``,
 but you can set a custom path at runtime in :struct:`arrow::ArrowGlobalOptions`::
 
-   arrow::ArrowGlobalOptions options;
-   options.tz_db_path = "path/to/tzdata";
+   arrow::GlobalOptions options;
+   options.timezone_db_path = "path/to/tzdata";
    ARROW_RETURN_NOT_OK(arrow::Initialize(options));
diff --git a/docs/source/cpp/examples/row_columnar_conversion.rst b/docs/source/cpp/examples/row_columnar_conversion.rst
@@ -33,22 +33,22 @@ instance, and then converts it back to the original array of structs.
 Dynamic Schemas
 ---------------
 
-In many cases, we need to convert to and from row data that does not have a 
+In many cases, we need to convert to and from row data that does not have a
 schema known at compile time. To help implement these conversions, this library
 provides several utilities:
 
-* :class:`arrow::RecordBatchBuilder`: creates and manages array builders for 
+* :class:`arrow::RecordBatchBuilder`: creates and manages array builders for
   a full record batch.
 * :func:`arrow::VisitTypeInline`: dispatch to functions specialized for the given
   array type.
 * :ref:`type-traits` (such as ``arrow::enable_if_primitive_ctype``): narrow template
-  functions to specific Arrow types, useful in conjunction with 
+  functions to specific Arrow types, useful in conjunction with
   the :ref:`cpp-visitor-pattern`.
 * :class:`arrow::TableBatchReader`: read a table in a batch at a time, with each
   batch being a zero-copy slice.
 
 The following example shows how to implement conversion between ``rapidjson::Document``
-and Arrow objects. You can read the full code example at 
+and Arrow objects. You can read the full code example at
 https://github.com/apache/arrow/blob/master/cpp/examples/arrow/rapidjson_row_converter.cc
 
 Writing conversions to Arrow
@@ -58,35 +58,35 @@ To convert rows to Arrow record batches, we'll setup Array builders for all the
 and then for each field iterate through row values and append to the builders.
 We assume that we already know the target schema, which may have
 been provided by another system or was inferred in another function. Inferring
-the schema *during* conversion is a challenging proposition; many systems will 
+the schema *during* conversion is a challenging proposition; many systems will
 check the first N rows to infer a schema if there is none already available.
 
 At the top level, we define a function ``ConvertToRecordBatch``:
 
 .. literalinclude:: ../../../../cpp/examples/arrow/rapidjson_row_converter.cc
    :language: cpp
    :start-at: arrow::Result<std::shared_ptr<arrow::RecordBatch>> ConvertToRecordBatch(
-   :end-at: } // ConvertToRecordBatch
+   :end-at: }  // ConvertToRecordBatch
    :linenos:
    :lineno-match:
 
 First we use :class:`arrow::RecordBatchBuilder`, which conveniently creates builders
 for each field in the schema. Then we iterate over the fields of the schema, get
 the builder, and call ``Convert()`` on our ``JsonValueConverter`` (to be discussed
-next). At the end, we call ``batch->ValidateFull()``, which checks the integrity 
+next). At the end, we call ``batch->ValidateFull()``, which checks the integrity
 of our arrays to make sure the conversion was performed correctly, which is useful
-for debugging new conversion implementations. 
+for debugging new conversion implementations.
 
 One level down, the ``JsonValueConverter`` is responsible for appending row values
 for the provided field to a provided array builder. In order to specialize logic
 for each data type, it implements ``Visit`` methods and calls :func:`arrow::VisitTypeInline`.
 (See more about type visitors in :ref:`cpp-visitor-pattern`.)
 
 At the end of that class is the private method ``FieldValues()``, which returns
-an iterator of the column values for the current field across the rows. In 
-row-based structures that are flat (such as a vector of values) this may be 
+an iterator of the column values for the current field across the rows. In
+row-based structures that are flat (such as a vector of values) this may be
 trivial to implement. But if the schema is nested, as in the case of JSON documents,
-a special iterator is needed to navigate the levels of nesting. See the 
+a special iterator is needed to navigate the levels of nesting. See the
 `full example <https://github.com/apache/arrow/blob/master/cpp/examples/arrow/rapidjson_row_converter.cc>`_
 for the implementation details of ``DocValuesIterator``.
 
@@ -100,7 +100,7 @@ for the implementation details of ``DocValuesIterator``.
 Writing conversions from Arrow
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To convert into rows *from* Arrow record batches, we'll process the table in 
+To convert into rows *from* Arrow record batches, we'll process the table in
 smaller batches, visiting each field of the batch and filling the output rows
 column-by-column.
 
@@ -109,7 +109,7 @@ for converting Arrow batches and tables to rows. In many cases, it's more optima
 to perform conversions to rows in smaller batches, rather than doing the entire
 table at once. So we define one ``ConvertToVector`` method to convert a single
 batch, then in the other conversion method we use :class:`arrow::TableBatchReader`
-to iterate over slices of a table. This returns Arrow's iterator type 
+to iterate over slices of a table. This returns Arrow's iterator type
 (:class:`arrow::Iterator`) so rows could then be processed either one-at-a-time
 or be collected into a container.
 
diff --git a/docs/source/developers/experimental_repos.rst b/docs/source/developers/experimental_repos.rst
@@ -15,8 +15,6 @@
 .. specific language governing permissions and limitations
 .. under the License.
 
-.. _experimental-repos:
-
 Experimental repositories
 =========================
 
diff --git a/docs/source/format/Versioning.rst b/docs/source/format/Versioning.rst
@@ -24,7 +24,7 @@ the **Format Version** and the **Library Version**. Each Library
 Version has a corresponding Format Version, and multiple versions of
 the library may have the same format version. For example, library
 versions 2.0.0 and 3.0.0 may both track format version 1.0.0. See
-:doc:`status` for details about supported features in each library.
+:doc:`../status` for details about supported features in each library.
 
 For library versions prior to 1.0.0, major releases may contain API
 changes. From 1.0.0 onward, we follow `Semantic Versioning
diff --git a/docs/source/java/cdata.rst b/docs/source/java/cdata.rst
@@ -27,8 +27,8 @@ through the :ref:`c-data-interface`, even between different language runtimes.
 Java to Python
 --------------
 
-Use this guide to implement :doc:`Java to Python <../python/integration/python_java.rst>`
-communication using the C Data Interface.
+See :doc:`../python/integration/python_java` to implement Java to
+Python communication using the C Data Interface.
 
 Java to C++
 -----------
@@ -37,7 +37,7 @@ Example: Share an Int64 array from C++ to Java:
 
 **C++ Side**
 
-Use this guide to :doc:`compile arrow <../developers/cpp/building.rst>` library:
+See :doc:`../developers/cpp/building` to build the Arrow C++ libraries:
 
 .. code-block:: shell
 
@@ -220,4 +220,4 @@ Let's create a Java class to test our bridge:
 
     C++-allocated array: [1, 2, 3, null, 5, 6, 7, 8, 9, 10]
 
-.. _`JavaCPP`: https://github.com/bytedeco/javacpp
+.. _`JavaCPP`: https://github.com/bytedeco/javacpp
diff --git a/docs/source/python/integration/python_java.rst b/docs/source/python/integration/python_java.rst
@@ -443,7 +443,7 @@ values printed by the Python script have been properly changed by the Java code:
     ]
 
 We can also use the C Stream Interface to exchange
-:py:class:`pyarrow.RecordBatchReader`s between Java and Python.  We'll
+:py:class:`pyarrow.RecordBatchReader` between Java and Python.  We'll
 use this Java class as a demo, which lets you read an Arrow IPC file
 via Java's implementation, or write data to a JSON file:
 
diff --git a/docs/source/status.rst b/docs/source/status.rst
@@ -21,8 +21,9 @@ Implementation Status
 
 The following tables summarize the features available in the various official
 Arrow libraries. All libraries currently follow version 1.0.0 of the Arrow
-format. See :doc:`versioning` for details about versioning. Unless otherwise stated,
-the Python, R, Ruby and C/GLib libraries follow the C++ Arrow library.
+format. See :doc:`./format/Versioning` for details about versioning. Unless
+otherwise stated, the Python, R, Ruby and C/GLib libraries follow the C++
+Arrow library.
 
 Data Types
 ==========
