diff --git a/ci/conda_env_sphinx.yml b/ci/conda_env_sphinx.yml index 8654d231065..49388e2b437 100644 --- a/ci/conda_env_sphinx.yml +++ b/ci/conda_env_sphinx.yml @@ -21,4 +21,4 @@ doxygen ipython # Pinned per ARROW-9693 sphinx=3.1.2 -sphinx_rtd_theme +pydata-sphinx-theme diff --git a/ci/docker/linux-apt-docs.dockerfile b/ci/docker/linux-apt-docs.dockerfile index 46c31bbd480..20cb889f28d 100644 --- a/ci/docker/linux-apt-docs.dockerfile +++ b/ci/docker/linux-apt-docs.dockerfile @@ -79,7 +79,7 @@ RUN pip install \ breathe \ ipython \ sphinx \ - sphinx_rtd_theme + pydata-sphinx-theme COPY c_glib/Gemfile /arrow/c_glib/ RUN gem install --no-document bundler && \ diff --git a/docs/requirements.txt b/docs/requirements.txt index 80411408149..0dbca692225 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,4 +2,4 @@ breathe ipython numpydoc sphinx==2.4.4 -sphinx_rtd_theme +pydata-sphinx-theme diff --git a/docs/source/_static/arrow.png b/docs/source/_static/arrow.png new file mode 100644 index 00000000000..72104b075b8 Binary files /dev/null and b/docs/source/_static/arrow.png differ diff --git a/docs/source/_static/favicon.ico b/docs/source/_static/favicon.ico new file mode 100644 index 00000000000..33a554a8a82 Binary files /dev/null and b/docs/source/_static/favicon.ico differ diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css index 91670a741e5..f623b3b3c49 100644 --- a/docs/source/_static/theme_overrides.css +++ b/docs/source/_static/theme_overrides.css @@ -17,6 +17,59 @@ * under the License. */ + +/* Customizing with theme CSS variables */ + +:root { + --pst-color-active-navigation: 215, 70, 51; + --pst-color-link-hover: 215, 70, 51; + --pst-color-headerlink: 215, 70, 51; + /* Use normal text color (like h3, ..) instead of primary color */ + --pst-color-h1: var(--color-text-base); + --pst-color-h2: var(--color-text-base); + /* Use softer blue from bootstrap's default info color */ + --pst-color-info: 23, 162, 184; + --pst-header-height: 0px; +} + +code { + color: rgb(215, 70, 51); +} + +.footer { + text-align: center; +} + +/* Ensure the logo is properly displayed */ + +.navbar-brand { + height: auto; + width: auto; +} + +a.navbar-brand img { + height: auto; + width: auto; + max-height: 15vh; + max-width: 100%; +} + + +/* Limit the max height of the sidebar navigation section. Because in our +custimized template, there is more content above the navigation, i.e. +larger logo: if we don't decrease the max-height, it will overlap with +the footer. +Details: min(15vh, 110px) for the logo size, 8rem for search box etc*/ + +@media (min-width:720px) { + @supports (position:-webkit-sticky) or (position:sticky) { + .bd-links { + max-height: calc(100vh - min(15vh, 110px) - 8rem) + } + } +} + + /* Fix table text wrapping in RTD theme, * see https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */ diff --git a/docs/source/_templates/docs-sidebar.html b/docs/source/_templates/docs-sidebar.html new file mode 100644 index 00000000000..f6ee66cadaa --- /dev/null +++ b/docs/source/_templates/docs-sidebar.html @@ -0,0 +1,19 @@ + + + + + +
+ + +
+ + diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index 8ee71e4bb27..a9d0f30bcf8 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -1,13 +1,5 @@ -{# Import the theme's layout. #} -{% extends "!layout.html" %} +{% extends "pydata_sphinx_theme/layout.html" %} -{%- block footer %} - - +{# Silence the navbar #} +{% block docs_navbar %} {% endblock %} diff --git a/docs/source/conf.py b/docs/source/conf.py index 47d88a9a166..05a45531f4a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -179,14 +179,15 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +html_theme = 'pydata_sphinx_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # html_theme_options = { - 'nosidebar': True + "show_toc_level": 2, + "google_analytics_id": "UA-107500873-1", } # Add any paths that contain custom themes here, relative to this directory. @@ -204,13 +205,13 @@ # The name of an image file (relative to this directory) to place at the top # of the sidebar. # -# html_logo = None +html_logo = "_static/arrow.png" # The name of an image file (relative to this directory) to use as a favicon of # the docs. This file should be a Windows icon file (.ico) being 16x16 or # 32x32 pixels large. # -# html_favicon = None +html_favicon = "_static/favicon.ico" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -239,7 +240,10 @@ # Custom sidebar templates, maps document names to template names. # -# html_sidebars = {} +html_sidebars = { +# '**': ['sidebar-logo.html', 'sidebar-search-bs.html', 'sidebar-nav-bs.html'], + '**': ['docs-sidebar.html'], +} # Additional templates that should be rendered to pages, maps page names to # template names. diff --git a/docs/source/cpp/api/array.rst b/docs/source/cpp/api/array.rst index 70e21faa011..bb981d1a047 100644 --- a/docs/source/cpp/api/array.rst +++ b/docs/source/cpp/api/array.rst @@ -19,10 +19,6 @@ Arrays ====== -.. sidebar:: Contents - - .. contents:: :local: - .. doxygenclass:: arrow::Array :project: arrow_cpp :members: diff --git a/docs/source/cpp/api/compute.rst b/docs/source/cpp/api/compute.rst index 9a71cce1288..3b0a89f83f8 100644 --- a/docs/source/cpp/api/compute.rst +++ b/docs/source/cpp/api/compute.rst @@ -18,10 +18,6 @@ Compute Functions ================= -.. sidebar:: Contents - - .. contents:: :local: - Datum class ----------- diff --git a/docs/source/cpp/api/dataset.rst b/docs/source/cpp/api/dataset.rst index f285f3633be..3f0df8a4537 100644 --- a/docs/source/cpp/api/dataset.rst +++ b/docs/source/cpp/api/dataset.rst @@ -19,10 +19,6 @@ Dataset ======= -.. sidebar:: Contents - - .. contents:: :local: - Interface ========= diff --git a/docs/source/cpp/api/filesystem.rst b/docs/source/cpp/api/filesystem.rst index 957e7321730..02fff9a6c2e 100644 --- a/docs/source/cpp/api/filesystem.rst +++ b/docs/source/cpp/api/filesystem.rst @@ -19,10 +19,6 @@ Filesystems =========== -.. sidebar:: Contents - - .. contents:: :local: - Interface ========= diff --git a/docs/source/cpp/api/io.rst b/docs/source/cpp/api/io.rst index 37023ec696c..735136a0d47 100644 --- a/docs/source/cpp/api/io.rst +++ b/docs/source/cpp/api/io.rst @@ -19,10 +19,6 @@ Input / output ============== -.. sidebar:: Contents - - .. contents:: :local: - Interfaces ========== diff --git a/docs/source/cpp/api/ipc.rst b/docs/source/cpp/api/ipc.rst index 2a9e656fa05..6822b986a75 100644 --- a/docs/source/cpp/api/ipc.rst +++ b/docs/source/cpp/api/ipc.rst @@ -22,10 +22,6 @@ Arrow IPC ========= -.. sidebar:: Contents - - .. contents:: :local: - IPC options =========== diff --git a/docs/source/cpp/compute.rst b/docs/source/cpp/compute.rst index b2ecb3b2ceb..92ac8886f87 100644 --- a/docs/source/cpp/compute.rst +++ b/docs/source/cpp/compute.rst @@ -23,10 +23,6 @@ Compute Functions ================= -.. sidebar:: Contents - - .. contents:: :local: - The generic Compute API ======================= diff --git a/docs/source/cpp/memory.rst b/docs/source/cpp/memory.rst index ac1ae5e4f27..415a3ae1852 100644 --- a/docs/source/cpp/memory.rst +++ b/docs/source/cpp/memory.rst @@ -25,10 +25,6 @@ Memory Management .. seealso:: :doc:`Memory management API reference ` -.. sidebar:: Contents - - .. contents:: :local: - Buffers ======= diff --git a/docs/source/cpp/parquet.rst b/docs/source/cpp/parquet.rst index a81fadb8eda..d69bf1c6b56 100644 --- a/docs/source/cpp/parquet.rst +++ b/docs/source/cpp/parquet.rst @@ -27,10 +27,6 @@ Reading and writing Parquet files .. seealso:: :ref:`Parquet reader and writer API reference `. -.. sidebar:: Contents - - .. contents:: :local: - The `Parquet format `__ is a space-efficient columnar storage format for complex data. The Parquet C++ implementation is part of the Apache Arrow project and benefits diff --git a/docs/source/developers/cpp/windows.rst b/docs/source/developers/cpp/windows.rst index 8df443d097a..4de67ba402c 100644 --- a/docs/source/developers/cpp/windows.rst +++ b/docs/source/developers/cpp/windows.rst @@ -194,7 +194,7 @@ to the Unix-specific ``ccache``). Newer versions of Visual Studio include Ninja. To see if your Visual Studio includes Ninja, run the initialization command shown :ref:`above` (``vcvarsall.bat`` or ``VsDevCmd.bat``), then - run ``ninja --version``. +run ``ninja --version``. If Ninja is not included in your version of Visual Studio, and you are using conda, activate your conda environment and install Ninja and clcache: diff --git a/docs/source/format/Guidelines.rst b/docs/source/format/Guidelines.rst index fec6c7f4f26..40624521a7a 100644 --- a/docs/source/format/Guidelines.rst +++ b/docs/source/format/Guidelines.rst @@ -15,6 +15,8 @@ .. specific language governing permissions and limitations .. under the License. +:orphan: + Implementation Guidelines ========================= diff --git a/docs/source/format/IPC.rst b/docs/source/format/IPC.rst index cc9f4198618..65b47f7d71c 100644 --- a/docs/source/format/IPC.rst +++ b/docs/source/format/IPC.rst @@ -15,6 +15,8 @@ .. specific language governing permissions and limitations .. under the License. +:orphan: + IPC === diff --git a/docs/source/format/Layout.rst b/docs/source/format/Layout.rst index cb83ae152f8..4568f31c58c 100644 --- a/docs/source/format/Layout.rst +++ b/docs/source/format/Layout.rst @@ -15,6 +15,8 @@ .. specific language governing permissions and limitations .. under the License. +:orphan: + Physical Memory Layout ====================== diff --git a/docs/source/format/Metadata.rst b/docs/source/format/Metadata.rst index ae15bf286f6..55045abb0af 100644 --- a/docs/source/format/Metadata.rst +++ b/docs/source/format/Metadata.rst @@ -15,6 +15,8 @@ .. specific language governing permissions and limitations .. under the License. +:orphan: + Format Metadata =============== diff --git a/docs/source/python/plasma.rst b/docs/source/python/plasma.rst index 25248c16a77..e373bd0a69d 100644 --- a/docs/source/python/plasma.rst +++ b/docs/source/python/plasma.rst @@ -21,9 +21,6 @@ The Plasma In-Memory Object Store ================================= -.. contents:: Contents - :depth: 3 - .. note:: As present, Plasma is only supported for use on Linux and macOS. diff --git a/python/pyarrow/dataset.py b/python/pyarrow/dataset.py index 615cb2516dc..9390fe8248f 100644 --- a/python/pyarrow/dataset.py +++ b/python/pyarrow/dataset.py @@ -517,8 +517,8 @@ def dataset(source, schema=None, format=None, filesystem=None, Parameters ---------- - source : path, list of paths, dataset, list of datasets, (list of) batches - or tables, iterable of batches, RecordBatchReader, or URI + source : path, list of paths, dataset, list of datasets, (list of) batches\ +or tables, iterable of batches, RecordBatchReader, or URI Path pointing to a single file: Open a FileSystemDataset from a single file. Path pointing to a directory: diff --git a/python/pyarrow/parquet.py b/python/pyarrow/parquet.py index 1b3602de8cd..4564740bc83 100644 --- a/python/pyarrow/parquet.py +++ b/python/pyarrow/parquet.py @@ -547,8 +547,8 @@ def _sanitize_table(table, new_schema, flavor): LogicalTypes.md#nested-types>`_, defaults to ``False``. For ``use_compliant_nested_type=True``, this will write into a list with 3-level structure where the middle level, named ``list``, - is a repeated group with a single field named ``element`` - :: + is a repeated group with a single field named ``element``:: + group (LIST) { repeated group list { element; @@ -558,8 +558,8 @@ def _sanitize_table(table, new_schema, flavor): For ``use_compliant_nested_type=False``, this will also write into a list with 3-level structure, where the name of the single field of the middle level ``list`` is taken from the element name for nested columns in Arrow, - which defaults to ``item`` - :: + which defaults to ``item``:: + group (LIST) { repeated group list { item;