From 51a8b7a95e38d8feb4d01d03a0d5bf2ea61376c4 Mon Sep 17 00:00:00 2001 From: AlenkaF Date: Mon, 26 Jun 2023 09:27:37 +0200 Subject: [PATCH 1/9] Move the sphinx pin up to version 6.x and add some of the warning corrections --- ci/conda_env_sphinx.txt | 2 +- docs/requirements.txt | 2 +- docs/source/cpp/build_system.rst | 1 + docs/source/developers/java/building.rst | 2 +- docs/source/format/CDeviceDataInterface.rst | 6 +++--- 5 files changed, 7 insertions(+), 6 deletions(-) diff --git a/ci/conda_env_sphinx.txt b/ci/conda_env_sphinx.txt index 22bb4fda06346..5e4545ca5e3de 100644 --- a/ci/conda_env_sphinx.txt +++ b/ci/conda_env_sphinx.txt @@ -22,7 +22,7 @@ ipython numpydoc pydata-sphinx-theme==0.8 sphinx-design -sphinx>=4.2,<6 +sphinx>=4.2,<7 sphinx-copybutton # Requirement for doctest-cython pytest-cython diff --git a/docs/requirements.txt b/docs/requirements.txt index cd9c7f0694228..d15d396ca6b6c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,5 +9,5 @@ pydata-sphinx-theme==0.8 sphinx-autobuild sphinx-design sphinx-copybutton -sphinx>=4.2,<6 +sphinx>=4.2,<7 pandas diff --git a/docs/source/cpp/build_system.rst b/docs/source/cpp/build_system.rst index f3f43c2a5fe6e..60df117eb510e 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/java/building.rst b/docs/source/developers/java/building.rst index c400b95f2439f..5af630ca94e75 100644 --- a/docs/source/developers/java/building.rst +++ b/docs/source/developers/java/building.rst @@ -195,7 +195,7 @@ CMake - To build all JNI libraries (MacOS / Linux) except the JNI C Data Interface library: - .. code-block:: + .. code-block:: text $ cd arrow $ brew bundle --file=cpp/Brewfile diff --git a/docs/source/format/CDeviceDataInterface.rst b/docs/source/format/CDeviceDataInterface.rst index ed3f3fb16d496..b54e6eabe0b2d 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 ` 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 From ed2fb7d91e583373c51c875f01b7c73d0bcb9adc Mon Sep 17 00:00:00 2001 From: AlenkaF Date: Mon, 26 Jun 2023 11:02:20 +0200 Subject: [PATCH 2/9] Add sphinxcontrib.jquery --- ci/conda_env_sphinx.txt | 4 +++- docs/requirements.txt | 1 + docs/source/conf.py | 1 + 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/ci/conda_env_sphinx.txt b/ci/conda_env_sphinx.txt index 5e4545ca5e3de..2ea24ba0d9e94 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,<7 sphinx-copybutton +sphinxcontrib-jquery +sphinx>=4.2,<7 # Requirement for doctest-cython pytest-cython pandas diff --git a/docs/requirements.txt b/docs/requirements.txt index d15d396ca6b6c..b9b221c7ade04 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,5 +9,6 @@ pydata-sphinx-theme==0.8 sphinx-autobuild sphinx-design sphinx-copybutton +sphinxcontrib-jquery sphinx>=4.2,<7 pandas diff --git a/docs/source/conf.py b/docs/source/conf.py index d1e8a31556f02..23b7070c4a84e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -115,6 +115,7 @@ 'IPython.sphinxext.ipython_console_highlighting', 'IPython.sphinxext.ipython_directive', 'numpydoc', + "sphinxcontrib.jquery", 'sphinx_design', 'sphinx_copybutton', 'sphinx.ext.autodoc', From bb3e821a251f392c2fb843c4008660aa713884e8 Mon Sep 17 00:00:00 2001 From: AlenkaF Date: Tue, 27 Jun 2023 09:26:02 +0200 Subject: [PATCH 3/9] Try unpinning upper version of Sphinx --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index b9b221c7ade04..515b017721b06 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -10,5 +10,5 @@ sphinx-autobuild sphinx-design sphinx-copybutton sphinxcontrib-jquery -sphinx>=4.2,<7 +sphinx>=4.2 pandas From 564385c0841d46dbc5c3425c0f902312bf8f337c Mon Sep 17 00:00:00 2001 From: AlenkaF Date: Tue, 27 Jun 2023 09:42:39 +0200 Subject: [PATCH 4/9] Remove pin in conda_env_sphinx also --- ci/conda_env_sphinx.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/conda_env_sphinx.txt b/ci/conda_env_sphinx.txt index 2ea24ba0d9e94..659b642a533c4 100644 --- a/ci/conda_env_sphinx.txt +++ b/ci/conda_env_sphinx.txt @@ -25,7 +25,7 @@ sphinx-autobuild sphinx-design sphinx-copybutton sphinxcontrib-jquery -sphinx>=4.2,<7 +sphinx>=4.2 # Requirement for doctest-cython pytest-cython pandas From 43dc9e88d7404d177ccd63eea697b3d146e0b7ff Mon Sep 17 00:00:00 2001 From: AlenkaF Date: Thu, 29 Jun 2023 14:49:08 +0200 Subject: [PATCH 5/9] Pin Sphinx version 6.2 --- ci/conda_env_sphinx.txt | 2 +- docs/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ci/conda_env_sphinx.txt b/ci/conda_env_sphinx.txt index 659b642a533c4..bd08937ae81be 100644 --- a/ci/conda_env_sphinx.txt +++ b/ci/conda_env_sphinx.txt @@ -25,7 +25,7 @@ sphinx-autobuild sphinx-design sphinx-copybutton sphinxcontrib-jquery -sphinx>=4.2 +sphinx==6.2 # Requirement for doctest-cython pytest-cython pandas diff --git a/docs/requirements.txt b/docs/requirements.txt index 515b017721b06..a4e5f7197b553 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -10,5 +10,5 @@ sphinx-autobuild sphinx-design sphinx-copybutton sphinxcontrib-jquery -sphinx>=4.2 +sphinx==6.2 pandas From c41cbced65f0c45d46d05b17e6acc1c6875b4af2 Mon Sep 17 00:00:00 2001 From: AlenkaF Date: Mon, 3 Jul 2023 07:16:24 +0200 Subject: [PATCH 6/9] Add an option to build python docs on MacOs Montery --- docs/Makefile | 2 ++ docs/source/developers/documentation.rst | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/docs/Makefile b/docs/Makefile index 90cb83ccb59a2..95a0c23ccf4e2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -150,6 +150,8 @@ cpp-live: .PHONY: python python: + # Remove the following line when sphinx issue (https://github.com/sphinx-doc/sphinx/issues/10943) is closed + python -m pip install ../python --quiet --no-dependencies $(SPHINXBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/python $(BUILDDIR)/html/python @echo @echo "Build finished. The HTML files are in $(BUILDDIR)/html/python" diff --git a/docs/source/developers/documentation.rst b/docs/source/developers/documentation.rst index f18a88bd3a5d3..d38980fd6fb50 100644 --- a/docs/source/developers/documentation.rst +++ b/docs/source/developers/documentation.rst @@ -87,6 +87,14 @@ These two steps are mandatory and must be executed in order. not sufficiently comprehensive. Portions of the Python API documentation will also not build without CUDA support having been built. +.. note:: + + If you are working on the Python documentation and are building the documentation + with ``pyarrow`` build from source on macOS Monterey, Python section of the + documentation might not be included in the ``_build/html`` when using the + ``make html`` command. In this case use ``make python`` to only build the + python part of the documentation. + After these steps are completed, the documentation is rendered in HTML 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 From a36c8891f7ad359ed569eddb729238f59d98c92f Mon Sep 17 00:00:00 2001 From: AlenkaF Date: Wed, 5 Jul 2023 09:57:56 +0200 Subject: [PATCH 7/9] Remove pip command from Makefile and update code-block in developers/java/building.rst --- docs/Makefile | 2 -- docs/source/developers/documentation.rst | 6 +++--- docs/source/developers/java/building.rst | 8 ++++---- 3 files changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 95a0c23ccf4e2..90cb83ccb59a2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -150,8 +150,6 @@ cpp-live: .PHONY: python python: - # Remove the following line when sphinx issue (https://github.com/sphinx-doc/sphinx/issues/10943) is closed - python -m pip install ../python --quiet --no-dependencies $(SPHINXBUILD) -b html $(SPHINXOPTS) -c $(SOURCEDIR) $(SOURCEDIR)/python $(BUILDDIR)/html/python @echo @echo "Build finished. The HTML files are in $(BUILDDIR)/html/python" diff --git a/docs/source/developers/documentation.rst b/docs/source/developers/documentation.rst index d38980fd6fb50..7e4f3bc2fd068 100644 --- a/docs/source/developers/documentation.rst +++ b/docs/source/developers/documentation.rst @@ -91,9 +91,9 @@ These two steps are mandatory and must be executed in order. If you are working on the Python documentation and are building the documentation with ``pyarrow`` build from source on macOS Monterey, Python section of the - documentation might not be included in the ``_build/html`` when using the - ``make html`` command. In this case use ``make python`` to only build the - python part of the documentation. + documentation might not be included in the ``_build/html``. In this case run + ``python -m pip install ../python --quiet --no-dependencies python`` before + running the ``make html`` command. After these steps are completed, the documentation is rendered in HTML format in ``arrow/docs/_build/html``. In particular, you can point your browser diff --git a/docs/source/developers/java/building.rst b/docs/source/developers/java/building.rst index 5af630ca94e75..5b525d467731e 100644 --- a/docs/source/developers/java/building.rst +++ b/docs/source/developers/java/building.rst @@ -195,14 +195,14 @@ CMake - To build all JNI libraries (MacOS / Linux) except the JNI C Data Interface library: - .. code-block:: text + .. code-block:: $ 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= $ mkdir -p java-dist cpp-jni $ cmake \ From ed74346f204a26ef544d8e8d97371ce521f769dd Mon Sep 17 00:00:00 2001 From: AlenkaF Date: Thu, 6 Jul 2023 07:01:18 +0200 Subject: [PATCH 8/9] Update note in the dev docs --- docs/source/developers/documentation.rst | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/source/developers/documentation.rst b/docs/source/developers/documentation.rst index 7e4f3bc2fd068..12fbc1b136766 100644 --- a/docs/source/developers/documentation.rst +++ b/docs/source/developers/documentation.rst @@ -87,18 +87,25 @@ These two steps are mandatory and must be executed in order. not sufficiently comprehensive. Portions of the Python API documentation will also not build without CUDA support having been built. +After these steps are completed, the documentation is rendered in HTML +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, Python section of the - documentation might not be included in the ``_build/html``. In this case run - ``python -m pip install ../python --quiet --no-dependencies python`` before - running the ``make html`` command. + documentation might not be included in the ``_build/html``. In this case try + installing ``pyarrow`` in editable version first before running the ``make html`` + command. -After these steps are completed, the documentation is rendered in HTML -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. + .. code-block:: shell + + pushd arrow/docs + python -m pip install ../python --quiet + make html + popd Building with Docker -------------------- From 29a6d5b6464fe5e2aac46d49543149a60e32f912 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 6 Jul 2023 08:57:35 +0200 Subject: [PATCH 9/9] Update docs/source/developers/documentation.rst --- docs/source/developers/documentation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/developers/documentation.rst b/docs/source/developers/documentation.rst index 12fbc1b136766..fcd8e84c7ac4d 100644 --- a/docs/source/developers/documentation.rst +++ b/docs/source/developers/documentation.rst @@ -95,9 +95,9 @@ you made. .. note:: If you are working on the Python documentation and are building the documentation - with ``pyarrow`` build from source on macOS Monterey, Python section of the - documentation might not be included in the ``_build/html``. In this case try - installing ``pyarrow`` in editable version first before running the ``make html`` + 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