This is an automated email from the ASF dual-hosted git repository.
jorisvandenbossche pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 82bf1e28ba GH-35403: [Docs] Support sphinx 6 for building the docs
(#36296)
82bf1e28ba is described below
commit 82bf1e28baca2226976163ca91ec4965712fbd8f
Author: Alenka Frim <[email protected]>
AuthorDate: Thu Jul 6 09:03:21 2023 +0200
GH-35403: [Docs] Support sphinx 6 for building the docs (#36296)
### What changes are included in this PR?
Enable the docs to be built with sphinx 6.x.
- Update the pin in the `requirements.txt`
- Add `sphinxcontrib.jquery` to include jQuery which is used in the
dropdown.
### Are these changes tested?
The Sphinx version update and the dropdown are tested locally.
### Are there any user-facing changes?
No.
* Closes: #35403
Lead-authored-by: AlenkaF <[email protected]>
Co-authored-by: Joris Van den Bossche <[email protected]>
Signed-off-by: Joris Van den Bossche <[email protected]>
---
ci/conda_env_sphinx.txt | 4 +++-
docs/requirements.txt | 3 ++-
docs/source/conf.py | 1 +
docs/source/cpp/build_system.rst | 1 +
docs/source/developers/documentation.rst | 15 +++++++++++++++
docs/source/developers/java/building.rst | 6 +++---
docs/source/format/CDeviceDataInterface.rst | 6 +++---
7 files changed, 28 insertions(+), 8 deletions(-)
diff --git a/ci/conda_env_sphinx.txt b/ci/conda_env_sphinx.txt
index 22bb4fda06..bd08937ae8 100644
--- a/ci/conda_env_sphinx.txt
+++ b/ci/conda_env_sphinx.txt
@@ -21,9 +21,11 @@ doxygen
ipython
numpydoc
pydata-sphinx-theme==0.8
+sphinx-autobuild
sphinx-design
-sphinx>=4.2,<6
sphinx-copybutton
+sphinxcontrib-jquery
+sphinx==6.2
# Requirement for doctest-cython
pytest-cython
pandas
diff --git a/docs/requirements.txt b/docs/requirements.txt
index cd9c7f0694..a4e5f7197b 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -9,5 +9,6 @@ pydata-sphinx-theme==0.8
sphinx-autobuild
sphinx-design
sphinx-copybutton
-sphinx>=4.2,<6
+sphinxcontrib-jquery
+sphinx==6.2
pandas
diff --git a/docs/source/conf.py b/docs/source/conf.py
index d1e8a31556..23b7070c4a 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -115,6 +115,7 @@ extensions = [
'IPython.sphinxext.ipython_console_highlighting',
'IPython.sphinxext.ipython_directive',
'numpydoc',
+ "sphinxcontrib.jquery",
'sphinx_design',
'sphinx_copybutton',
'sphinx.ext.autodoc',
diff --git a/docs/source/cpp/build_system.rst b/docs/source/cpp/build_system.rst
index f3f43c2a5f..60df117eb5 100644
--- a/docs/source/cpp/build_system.rst
+++ b/docs/source/cpp/build_system.rst
@@ -45,6 +45,7 @@ This minimal ``CMakeLists.txt`` file compiles a
``my_example.cc`` source
file into an executable linked with the Arrow C++ shared library:
.. code-block:: cmake
+
cmake_minimum_required(VERSION 3.16)
project(MyExample)
diff --git a/docs/source/developers/documentation.rst
b/docs/source/developers/documentation.rst
index f18a88bd3a..fcd8e84c7a 100644
--- a/docs/source/developers/documentation.rst
+++ b/docs/source/developers/documentation.rst
@@ -92,6 +92,21 @@ format in ``arrow/docs/_build/html``. In particular, you
can point your browser
at ``arrow/docs/_build/html/index.html`` to read the docs and review any
changes
you made.
+.. note::
+
+ If you are working on the Python documentation and are building the
documentation
+ with ``pyarrow`` build from source on macOS Monterey, the Python section of
the
+ documentation might not be included in the ``_build/html``. In this case,
try
+ installing ``pyarrow`` in non-editable mode first before running the ``make
html``
+ command.
+
+ .. code-block:: shell
+
+ pushd arrow/docs
+ python -m pip install ../python --quiet
+ make html
+ popd
+
Building with Docker
--------------------
diff --git a/docs/source/developers/java/building.rst
b/docs/source/developers/java/building.rst
index c400b95f24..5b525d4677 100644
--- a/docs/source/developers/java/building.rst
+++ b/docs/source/developers/java/building.rst
@@ -199,10 +199,10 @@ CMake
$ cd arrow
$ brew bundle --file=cpp/Brewfile
- Homebrew Bundle complete! 25 Brewfile dependencies now installed.
+ # Homebrew Bundle complete! 25 Brewfile dependencies now installed.
$ brew uninstall aws-sdk-cpp
- (We can't use aws-sdk-cpp installed by Homebrew because it has
- an issue: https://github.com/aws/aws-sdk-cpp/issues/1809 )
+ # (We can't use aws-sdk-cpp installed by Homebrew because it has
+ # an issue: https://github.com/aws/aws-sdk-cpp/issues/1809 )
$ export JAVA_HOME=<absolute path to your java home>
$ mkdir -p java-dist cpp-jni
$ cmake \
diff --git a/docs/source/format/CDeviceDataInterface.rst
b/docs/source/format/CDeviceDataInterface.rst
index ed3f3fb16d..b54e6eabe0 100644
--- a/docs/source/format/CDeviceDataInterface.rst
+++ b/docs/source/format/CDeviceDataInterface.rst
@@ -282,7 +282,7 @@ has the following fields:
data.
.. seealso::
- The :ref:`synchronization event types
<_c-device-data-interface-event-types>`
+ The :ref:`synchronization event types
<c-device-data-interface-event-types>`
section below.
.. c:member:: int64_t ArrowDeviceArray.reserved[3]
@@ -563,7 +563,7 @@ streaming source of Arrow arrays. It has the following
fields:
.. c:member:: ArrowDeviceType device_type
*Mandatory.* The device type that this stream produces data on. All
- ``ArrowDeviceArray``s that are produced by this stream should have the
+ ``ArrowDeviceArray`` s that are produced by this stream should have the
same device type as is set here. This is a convenience for the consumer
to not have to check every array that is retrieved and instead allows
higher-level coding constructs for streams.
@@ -675,7 +675,7 @@ is frozen. This means that the ``ArrowDeviceArray``
structure definition
should not change in any way -- including adding new members.
Backwards-compatible changes are allowed, for example new macro values for
-:c:typedef:`ArrowDeviceType` or converting the reserved 24 bytes into a
+:c:type:`ArrowDeviceType` or converting the reserved 24 bytes into a
different type/member without changing the size of the structure.
Any incompatible changes should be part of a new specification, for example
