apache · jorisvandenbossche · Apr 2, 2021 · Apr 2, 2021 · Apr 2, 2021 · Apr 2, 2021
diff --git 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
@@ -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
@@ -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
diff --git a/docs/source/_static/favicon.ico b/docs/source/_static/favicon.ico
diff --git 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
@@ -0,0 +1,19 @@
+
+<a class="navbar-brand" href="{{ pathto(master_doc) }}">
+  <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
+</a>
+
+<form class="bd-search d-flex align-items-center" action="{{ pathto('search') }}" method="get">
+  <i class="icon fas fa-search"></i>
+  <input type="search" class="form-control" name="q" id="search-input" placeholder="{{ theme_search_bar_text }}" aria-label="{{ theme_search_bar_text }}" autocomplete="off" >
+</form>
+
+<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
+  <div class="bd-toc-item active">
+    {% if "python/api" in pagename or "python/generated" in pagename %}
+    {{ generate_nav_html("sidebar", startdepth=0, maxdepth=3, collapse=False, includehidden=True, titles_only=True) }}
+    {% else %}
+    {{ generate_nav_html("sidebar", startdepth=0, maxdepth=4, collapse=False, includehidden=True, titles_only=True) }}
+    {% endif %}
+  </div>
+</nav>
diff --git 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 %}
-<script async src="https://www.googletagmanager.com/gtag/js?id=UA-107500873-1"></script>
-<script>
-  window.dataLayer = window.dataLayer || [];
-  function gtag(){dataLayer.push(arguments);}
-  gtag('js', new Date());
-
-  gtag('config', 'UA-107500873-1');
-</script>
+{# Silence the navbar #}
+{% block docs_navbar %}
 {% endblock %}
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -25,10 +25,6 @@ Memory Management
 .. seealso::
    :doc:`Memory management API reference <api/memory>`
 
-.. sidebar:: Contents
-
-   .. contents:: :local:
-
 Buffers
 =======
 

diff --git 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 <cpp-api-parquet>`.
 
-.. sidebar:: Contents
-
-   .. contents:: :local:
-
 The `Parquet format <https://parquet.apache.org/documentation/latest/>`__
 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
@@ -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<windows-system-setup>` (``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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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``::
+
         <list-repetition> group <name> (LIST) {
             repeated group list {
                   <element-repetition> <element-type> 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``::
+
         <list-repetition> group <name> (LIST) {
             repeated group list {
                 <element-repetition> <element-type> item;
-Original file line number
+Diff line change
@@ Expand Up / @@ -15,6 +15,8 @@ @@
     .. specific language governing permissions and limitations
     .. under the License.
+    :orphan:
     IPC
     ===
@@ Expand Down @@