You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by li...@apache.org on 2022/07/07 13:16:36 UTC
[arrow] branch master updated: ARROW-16994: [Docs][CI] Clean up docs warnings (#13533)
This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new 7922ed0d94 ARROW-16994: [Docs][CI] Clean up docs warnings (#13533)
7922ed0d94 is described below
commit 7922ed0d942eabcd12e970b96017ee9ead14bc32
Author: David Li <li...@gmail.com>
AuthorDate: Thu Jul 7 09:16:29 2022 -0400
ARROW-16994: [Docs][CI] Clean up docs warnings (#13533)
Authored-by: David Li <li...@gmail.com>
Signed-off-by: David Li <li...@gmail.com>
---
.github/workflows/docs_light.yml | 2 +-
docs/source/cpp/api/compute.rst | 3 ---
docs/source/cpp/api/datatype.rst | 2 ++
docs/source/cpp/api/flight.rst | 2 +-
docs/source/cpp/api/support.rst | 2 +-
docs/source/cpp/build_system.rst | 4 ++--
.../cpp/examples/row_columnar_conversion.rst | 26 +++++++++++-----------
docs/source/developers/experimental_repos.rst | 2 --
docs/source/format/Versioning.rst | 2 +-
docs/source/java/cdata.rst | 8 +++----
docs/source/python/integration/python_java.rst | 2 +-
docs/source/status.rst | 5 +++--
12 files changed, 29 insertions(+), 31 deletions(-)
diff --git a/.github/workflows/docs_light.yml b/.github/workflows/docs_light.yml
index afbaa1bd75..eee778e699 100644
--- 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
index c83894ef60..d64362a408 100644
--- 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
index b2d9c10efd..39c7913025 100644
--- 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
index 40bdfe008d..aa18a4e412 100644
--- 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
index ac1c6f6d9c..9aa524642d 100644
--- 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
index ff353f3832..95cfe4ce3f 100644
--- 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
index d3c0a98559..c4a20d29b4 100644
--- 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,7 +58,7 @@ 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``:
@@ -66,16 +66,16 @@ 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
@@ -83,10 +83,10 @@ for each data type, it implements ``Visit`` methods and calls :func:`arrow::Visi
(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
index f3a9da9489..f13adba2b1 100644
--- 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
index ec77490939..4158f6a003 100644
--- 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
index e5ba387750..7e5c2df1c5 100644
--- 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
\ No newline at end of file
+.. _`JavaCPP`: https://github.com/bytedeco/javacpp
diff --git a/docs/source/python/integration/python_java.rst b/docs/source/python/integration/python_java.rst
index a524fe9b48..8b086485cf 100644
--- 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
index 4caf0eb156..3c35a582c6 100644
--- 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
==========