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 7dc9f69a8a GH-36590: [Docs] Support Pydata Sphinx Theme 0.14.0 (#36591)
7dc9f69a8a is described below
commit 7dc9f69a8a77345d0ec7920af9224ef96d7f5f78
Author: Alenka Frim <[email protected]>
AuthorDate: Wed Sep 27 16:23:26 2023 +0200
GH-36590: [Docs] Support Pydata Sphinx Theme 0.14.0 (#36591)
Preview: http://crossbow.voltrondata.com/pr_docs/36591/
### Rationale for this change
The Pydata Sphinx Theme that we use for our documentation has been pinned
due to bigger changes in the theme layout. It needs to be unpinned and our
layout needs to be updated.
### What changes are included in this PR?
Update of the Pydata Sphinx Theme and changes to our layout/structure:
- dark/light mode
- top menu bar
- search button in the top right navigation bar
- drop down from the theme layout in the top right navigation bar
- version warnings bar from the theme layout
- main landing page and the landing page for the dev docs
⚠️ Needs an update of the
[versions.json](https://github.com/apache/arrow-site/blob/AlenkaF-patch-1/docs/_static/versions.json)
### Are these changes tested?
Yes, locally. Will also add docs preview via GitHub actions.
### Are there any user-facing changes?
No.
* Closes: #32451
* Closes: #36590
Lead-authored-by: AlenkaF <[email protected]>
Co-authored-by: Sutou Kouhei <[email protected]>
Signed-off-by: Joris Van den Bossche <[email protected]>
---
ci/conda_env_sphinx.txt | 2 +-
dev/release/01-prepare-test.rb | 3 +-
dev/release/post-11-bump-versions-test.rb | 3 +-
dev/release/utils-update-docs-versions.py | 10 +-
docs/requirements.txt | 3 +-
docs/source/_static/arrow-dark.png | Bin 0 -> 91541 bytes
docs/source/_static/theme_overrides.css | 85 +--------
docs/source/_static/versions.json | 47 +++--
docs/source/_static/versionwarning.js | 2 +
docs/source/_templates/docs-sidebar.html | 25 ---
docs/source/_templates/layout.html | 10 --
docs/source/_templates/version-switcher.html | 60 -------
docs/source/c_glib/index.rst | 2 +
docs/source/conf.py | 37 +++-
docs/source/cpp/index.rst | 55 ++++--
.../developers/continuous_integration/index.rst | 1 +
.../developers/continuous_integration/overview.rst | 2 +-
docs/source/developers/contributing.rst | 190 --------------------
docs/source/developers/images/book-open-solid.svg | 2 +-
docs/source/developers/images/bug-solid.svg | 2 +-
docs/source/developers/images/code-solid.svg | 2 +-
docs/source/developers/images/users-solid.svg | 2 +-
docs/source/developers/index.rst | 198 ++++++++++++++++++++-
docs/source/developers/overview.rst | 6 +-
docs/source/developers/release.rst | 2 +
docs/source/format/index.rst | 7 +-
docs/source/index.rst | 115 +++++++-----
docs/source/java/index.rst | 3 +
docs/source/js/index.rst | 2 +
docs/source/python/index.rst | 8 +-
docs/source/r/index.rst | 2 +
31 files changed, 416 insertions(+), 472 deletions(-)
diff --git a/ci/conda_env_sphinx.txt b/ci/conda_env_sphinx.txt
index bd08937ae8..af1bfe9b78 100644
--- a/ci/conda_env_sphinx.txt
+++ b/ci/conda_env_sphinx.txt
@@ -20,7 +20,7 @@ breathe
doxygen
ipython
numpydoc
-pydata-sphinx-theme==0.8
+pydata-sphinx-theme
sphinx-autobuild
sphinx-design
sphinx-copybutton
diff --git a/dev/release/01-prepare-test.rb b/dev/release/01-prepare-test.rb
index 1062e8b06c..54437e9da6 100644
--- a/dev/release/01-prepare-test.rb
+++ b/dev/release/01-prepare-test.rb
@@ -170,7 +170,8 @@ class PrepareTest < Test::Unit::TestCase
"+ \"name\": \"#{@release_compatible_version}
(stable)\",",
"+ {",
"+ \"name\": \"#{@previous_compatible_version}\",",
- "+ \"version\": \"#{@previous_compatible_version}/\"",
+ "+ \"version\": \"#{@previous_compatible_version}/\",",
+ "+ \"url\":
\"https://arrow.apache.org/docs/#{@previous_compatible_version}/\"";,
"+ },",
],
],
diff --git a/dev/release/post-11-bump-versions-test.rb
b/dev/release/post-11-bump-versions-test.rb
index 0ef4646236..8253472ccc 100644
--- a/dev/release/post-11-bump-versions-test.rb
+++ b/dev/release/post-11-bump-versions-test.rb
@@ -148,7 +148,8 @@ class PostBumpVersionsTest < Test::Unit::TestCase
"+ \"name\": \"#{@release_compatible_version}
(stable)\",",
"+ {",
"+ \"name\": \"#{@previous_compatible_version}\",",
- "+ \"version\": \"#{@previous_compatible_version}/\"",
+ "+ \"version\": \"#{@previous_compatible_version}/\",",
+ "+ \"url\":
\"https://arrow.apache.org/docs/#{@previous_compatible_version}/\"";,
"+ },",
],
],
diff --git a/dev/release/utils-update-docs-versions.py
b/dev/release/utils-update-docs-versions.py
index 6e0137b7c8..7ca4059214 100644
--- a/dev/release/utils-update-docs-versions.py
+++ b/dev/release/utils-update-docs-versions.py
@@ -50,11 +50,15 @@ if release_type != "patch":
# Create new versions
new_versions = [
{"name": f"{dev_compatible_version} (dev)",
- "version": "dev/"},
+ "version": "dev/",
+ "url": "https://arrow.apache.org/docs/dev/"},
{"name": f"{stable_compatible_version} (stable)",
- "version": ""},
+ "version": "",
+ "url": "https://arrow.apache.org/docs/";,
+ "preferred": True},
{"name": previous_compatible_version,
- "version": f"{previous_compatible_version}/"},
+ "version": f"{previous_compatible_version}/",
+ "url":
f"https://arrow.apache.org/docs/{previous_compatible_version}/"},
*old_versions[2:],
]
with open(main_versions_path, 'w') as json_file:
diff --git a/docs/requirements.txt b/docs/requirements.txt
index a4e5f7197b..37a50d51dd 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -5,10 +5,9 @@
breathe
ipython
numpydoc
-pydata-sphinx-theme==0.8
+pydata-sphinx-theme
sphinx-autobuild
sphinx-design
sphinx-copybutton
-sphinxcontrib-jquery
sphinx==6.2
pandas
diff --git a/docs/source/_static/arrow-dark.png
b/docs/source/_static/arrow-dark.png
new file mode 100644
index 0000000000..618204a237
Binary files /dev/null and b/docs/source/_static/arrow-dark.png differ
diff --git a/docs/source/_static/theme_overrides.css
b/docs/source/_static/theme_overrides.css
index e64d40f111..eeba0ef4cc 100644
--- a/docs/source/_static/theme_overrides.css
+++ b/docs/source/_static/theme_overrides.css
@@ -21,43 +21,15 @@
/* 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%;
+ /* Change header hight to make the logo a bit larger */
+ --pst-header-height: 6rem;
+ /* Make headings more bold */
+ --pst-font-weight-heading: 600;
}
/* Contibuting landing page overview cards */
.contrib-card {
- background: #fff;
border-radius: 0;
padding: 30px 10px 20px 10px;
margin: 10px 0px;
@@ -70,12 +42,12 @@ a.navbar-brand img {
.contrib-card .sd-card-img-top {
margin: 2px;
height: 75px;
+ background: none !important;
}
.contrib-card .sd-card-title {
- /* color: rgb(var(--pst-color-h1)) !important; */
+ color: var(--pst-color-primary);
font-size: var(--pst-font-size-h3);
- /* font-weight: bold; */
padding: 1rem 0rem 0.5rem 0rem;
}
@@ -112,48 +84,3 @@ dl.cpp.enumerator {
p.breathe-sectiondef-title {
margin-top: 1rem;
}
-
-/* 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)
- }
- }
-}
-
-/* Styling to get the version dropdown and search box side-by-side on wide
screens */
-
-#version-search-wrapper {
- width: inherit;
- display: flex;
- flex-wrap: wrap;
- justify-content: left;
- align-items: center;
-}
-
-#version-button {
- padding-left: 0.5rem;
- padding-right: 1rem;
-}
-
-#search-box {
- flex: 1 0 12em;
-}
-
-/* Fix table text wrapping in RTD theme,
- * see https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
- */
-
-@media screen {
- table.docutils td {
- /* !important prevents the common CSS stylesheets from overriding
- this as on RTD they are loaded after this stylesheet */
- white-space: normal !important;
- }
-}
diff --git a/docs/source/_static/versions.json
b/docs/source/_static/versions.json
index f91b0a17e7..8d9c5878c8 100644
--- a/docs/source/_static/versions.json
+++ b/docs/source/_static/versions.json
@@ -1,62 +1,73 @@
[
{
"name": "14.0 (dev)",
- "version": "dev/"
+ "version": "dev/",
+ "url": "https://arrow.apache.org/docs/dev/";
},
{
"name": "13.0 (stable)",
- "version": ""
+ "version": "",
+ "url": "https://arrow.apache.org/docs/";,
+ "preferred": true
},
{
"name": "12.0",
- "version": "12.0/"
- },
- {
- "name": "12.0",
- "version": "12.0/"
+ "version": "12.0/",
+ "url": "https://arrow.apache.org/docs/12.0/";
},
{
"name": "11.0",
- "version": "11.0/"
+ "version": "11.0/",
+ "url": "https://arrow.apache.org/docs/11.0/";
},
{
"name": "10.0",
- "version": "10.0/"
+ "version": "10.0/",
+ "url": "https://arrow.apache.org/docs/10.0/";
},
{
"name": "9.0",
- "version": "9.0/"
+ "version": "9.0/",
+ "url": "https://arrow.apache.org/docs/9.0/";
},
{
"name": "8.0",
- "version": "8.0/"
+ "version": "8.0/",
+ "url": "https://arrow.apache.org/docs/8.0/";
},
{
"name": "7.0",
- "version": "7.0/"
+ "version": "7.0/",
+ "url": "https://arrow.apache.org/docs/7.0/";
},
{
"name": "6.0",
- "version": "6.0/"
+ "version": "6.0/",
+ "url": "https://arrow.apache.org/docs/6.0/";
},
{
"name": "5.0",
- "version": "5.0/"
+ "version": "5.0/",
+ "url": "https://arrow.apache.org/docs/5.0/";
},
{
"name": "4.0",
- "version": "4.0/"
+ "version": "4.0/",
+ "url": "https://arrow.apache.org/docs/4.0/";
},
{
"name": "3.0",
- "version": "3.0/"
+ "version": "3.0/",
+ "url": "https://arrow.apache.org/docs/3.0/";
},
{
"name": "2.0",
- "version": "2.0/"
+ "version": "2.0/",
+ "url": "https://arrow.apache.org/docs/2.0/";
},
{
"name": "1.0",
- "version": "1.0/"
+ "version": "1.0/",
+ "url": "https://arrow.apache.org/docs/dev/";
}
]
diff --git a/docs/source/_static/versionwarning.js
b/docs/source/_static/versionwarning.js
index 601b93b75d..e53c160ed9 100644
--- a/docs/source/_static/versionwarning.js
+++ b/docs/source/_static/versionwarning.js
@@ -17,6 +17,8 @@
(function() {
// adapted 2022-11 from https://mne.tools/versionwarning.js
+ // Not used anymore for versions 14.0.0 and higher
+ // Kept for older docs versions (13.0.0 and lower)
if (location.hostname == 'arrow.apache.org') {
$.getJSON("https://arrow.apache.org/docs/_static/versions.json";,
function(data){
var latestStable = data[1].name.replace(" (stable)","");
diff --git a/docs/source/_templates/docs-sidebar.html
b/docs/source/_templates/docs-sidebar.html
deleted file mode 100644
index 26d42a82f1..0000000000
--- a/docs/source/_templates/docs-sidebar.html
+++ /dev/null
@@ -1,25 +0,0 @@
-
-<a class="navbar-brand" href="{{ pathto(master_doc) }}">
- <img src="{{ logo_url|e }}" class="logo" alt="logo">
-</a>
-
-<div id="version-search-wrapper">
-
-{% include "version-switcher.html" %}
-
-<form id="search-box" 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>
-
-</div>
-
-<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
index ca39e8e5a8..956e0142c5 100644
--- a/docs/source/_templates/layout.html
+++ b/docs/source/_templates/layout.html
@@ -22,13 +22,3 @@
</script>
<!-- End Matomo Code -->
{% endblock %}
-
-{# Silence the navbar #}
-{% block docs_navbar %}
-{% endblock %}
-
-{# Add version warnings #}
-{% block footer %}
- {{ super() }}
- <script type="text/javascript"
src="/docs/_static/versionwarning.js"></script>
-{% endblock %}
diff --git a/docs/source/_templates/version-switcher.html
b/docs/source/_templates/version-switcher.html
deleted file mode 100644
index 24a8c15ac0..0000000000
--- a/docs/source/_templates/version-switcher.html
+++ /dev/null
@@ -1,60 +0,0 @@
-<div id="version-button" class="dropdown">
- <button type="button" class="btn btn-secondary btn-sm navbar-btn
dropdown-toggle" id="version_switcher_button" data-toggle="dropdown">
- {{ release }}
- <span class="caret"></span>
- </button>
- <div id="version_switcher" class="dropdown-menu list-group-flush py-0"
aria-labelledby="version_switcher_button">
- <!-- dropdown will be populated by javascript on page load -->
- </div>
-</div>
-
-<script type="text/javascript">
-// Function to construct the target URL from the JSON components
-function buildURL(entry) {
- var template = "{{ switcher_template_url }}"; // supplied by jinja
- template = template.replace("{version}", entry.version);
- return template;
-}
-
-// Function to check if corresponding page path exists in other version of docs
-// and, if so, go there instead of the homepage of the other docs version
-function checkPageExistsAndRedirect(event) {
- const currentFilePath = "{{ pagename }}.html",
- otherDocsHomepage = event.target.getAttribute("href");
- let tryUrl = `${otherDocsHomepage}${currentFilePath}`;
- $.ajax({
- type: 'HEAD',
- url: tryUrl,
- // if the page exists, go there
- success: function() {
- location.href = tryUrl;
- }
- }).fail(function() {
- location.href = otherDocsHomepage;
- });
- return false;
-}
-
-// Function to populate the version switcher
-(function () {
- // get JSON config
- $.getJSON("{{ switcher_json_url }}", function(data, textStatus, jqXHR) {
- // create the nodes first (before AJAX calls) to ensure the order is
- // correct (for now, links will go to doc version homepage)
- $.each(data, function(index, entry) {
- // if no custom name specified (e.g., "latest"), use version string
- if (!("name" in entry)) {
- entry.name = entry.version;
- }
- // construct the appropriate URL, and add it to the dropdown
- entry.url = buildURL(entry);
- const node = document.createElement("a");
- node.setAttribute("class", "list-group-item list-group-item-action
py-1");
- node.setAttribute("href", `${entry.url}`);
- node.textContent = `${entry.name}`;
- node.onclick = checkPageExistsAndRedirect;
- $("#version_switcher").append(node);
- });
- });
-})();
-</script>
diff --git a/docs/source/c_glib/index.rst b/docs/source/c_glib/index.rst
index 56db23f2a2..b10524eb2e 100644
--- a/docs/source/c_glib/index.rst
+++ b/docs/source/c_glib/index.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _c-glib:
+
C/GLib docs
===========
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 23b7070c4a..e9e8969f55 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -115,7 +115,6 @@ extensions = [
'IPython.sphinxext.ipython_console_highlighting',
'IPython.sphinxext.ipython_directive',
'numpydoc',
- "sphinxcontrib.jquery",
'sphinx_design',
'sphinx_copybutton',
'sphinx.ext.autodoc',
@@ -288,16 +287,37 @@ html_theme = 'pydata_sphinx_theme'
# further. For a list of options available for each theme, see the
# documentation.
#
+
html_theme_options = {
"show_toc_level": 2,
"use_edit_page_button": True,
+ "logo": {
+ "image_light": "_static/arrow.png",
+ "image_dark": "_static/arrow-dark.png",
+ },
+ "header_links_before_dropdown": 2,
+ "header_dropdown_text": "Language implementations",
+ "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
+ "icon_links": [
+ {
+ "name": "GitHub",
+ "url": "https://github.com/apache/arrow";,
+ "icon": "fa-brands fa-square-github",
+ },
+ {
+ "name": "Twitter",
+ "url": "https://twitter.com/ApacheArrow";,
+ "icon": "fa-brands fa-square-twitter",
+ },
+ ],
+ "show_version_warning_banner": True,
+ "switcher": {
+ "json_url": "/docs/_static/versions.json",
+ "version_match": version,
+ },
}
html_context = {
- "switcher_json_url": "/docs/_static/versions.json",
- "switcher_template_url": "https://arrow.apache.org/docs/{version}";,
- # for local testing
- # "switcher_template_url": "http://0.0.0.0:8000/docs/{version}";,
"github_user": "apache",
"github_repo": "arrow",
"github_version": "main",
@@ -319,7 +339,7 @@ html_title = u'Apache Arrow v{}'.format(version)
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
-html_logo = "_static/arrow.png"
+# 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
@@ -354,10 +374,9 @@ html_css_files = ['theme_overrides.css']
# 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'],
-}
+# }
# The base URL which points to the root of the HTML documentation,
# used for canonical url
diff --git a/docs/source/cpp/index.rst b/docs/source/cpp/index.rst
index e06453e202..6d4d4aaa81 100644
--- a/docs/source/cpp/index.rst
+++ b/docs/source/cpp/index.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _cpp:
+
C++ Implementation
==================
@@ -25,9 +27,9 @@ Welcome to the Apache Arrow C++ implementation documentation!
:padding: 2 2 0 0
:class-container: sd-text-center
- .. grid-item-card:: Basic understanding
+ .. grid-item-card:: Getting started
:class-card: contrib-card
- :shadow: md
+ :shadow: none
Start here to gain a basic understanding of Arrow with
an installation and linking guide, documentation of
@@ -37,14 +39,14 @@ Welcome to the Apache Arrow C++ implementation
documentation!
.. button-link:: getting_started.html
:click-parent:
- :color: secondary
+ :color: primary
:expand:
- Getting started
+ To Getting started
.. grid-item-card:: User Guide
:class-card: contrib-card
- :shadow: md
+ :shadow: none
Explore more specific topics and underlying concepts
of Arrow C++
@@ -53,19 +55,19 @@ Welcome to the Apache Arrow C++ implementation
documentation!
.. button-link:: user_guide.html
:click-parent:
- :color: secondary
+ :color: primary
:expand:
- User Guide
+ To the User Guide
.. grid:: 2
:gutter: 4
:padding: 2 2 0 0
:class-container: sd-text-center
- .. grid-item-card:: Examples of use
+ .. grid-item-card:: Examples
:class-card: contrib-card
- :shadow: md
+ :shadow: none
Find the description and location of the examples
using Arrow C++ library
@@ -74,14 +76,14 @@ Welcome to the Apache Arrow C++ implementation
documentation!
.. button-link:: examples/index.html
:click-parent:
- :color: secondary
+ :color: primary
:expand:
- Examples
+ To the Examples
- .. grid-item-card:: Reference documentation
+ .. grid-item-card:: API Reference
:class-card: contrib-card
- :shadow: md
+ :shadow: none
Explore Arrow’s API reference documentation
@@ -89,10 +91,32 @@ Welcome to the Apache Arrow C++ implementation
documentation!
.. button-link:: api.html
:click-parent:
- :color: secondary
+ :color: primary
+ :expand:
+
+ To the API Reference
+
+.. grid:: 1
+ :gutter: 4
+ :padding: 2 2 0 0
+ :class-container: sd-text-center
+
+ .. grid-item-card:: Cookbook
+ :class-card: contrib-card
+ :shadow: none
+
+ Collection of recipes which demonstrate how to
+ solve many common tasks that users might need
+ to perform when working with arrow data
+
+ +++
+
+ .. button-link:: https://arrow.apache.org/cookbook/cpp/
+ :click-parent:
+ :color: primary
:expand:
- API Reference
+ To the Cookbook
.. toctree::
:maxdepth: 2
@@ -102,3 +126,4 @@ Welcome to the Apache Arrow C++ implementation
documentation!
user_guide
Examples <examples/index>
api
+ C++ cookbook <https://arrow.apache.org/cookbook/cpp/>
diff --git a/docs/source/developers/continuous_integration/index.rst
b/docs/source/developers/continuous_integration/index.rst
index 6e8e26981c..f988b5ab69 100644
--- a/docs/source/developers/continuous_integration/index.rst
+++ b/docs/source/developers/continuous_integration/index.rst
@@ -15,6 +15,7 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _continuous_integration:
**********************
Continuous Integration
diff --git a/docs/source/developers/continuous_integration/overview.rst
b/docs/source/developers/continuous_integration/overview.rst
index 1d82e845a3..3e155bf600 100644
--- a/docs/source/developers/continuous_integration/overview.rst
+++ b/docs/source/developers/continuous_integration/overview.rst
@@ -20,7 +20,7 @@
Continuous Integration
======================
-Continuous Integration for Arrow is fairly complex as it needs to run across
different combinations of package managers, compilers, versions of multiple
sofware libraries, operating systems, and other potential sources of variation.
In this article, we will give an overview of its main components and the
relevant files and directories.
+Continuous Integration for Arrow is fairly complex as it needs to run across
different combinations of package managers, compilers, versions of multiple
software libraries, operating systems, and other potential sources of
variation. In this article, we will give an overview of its main components
and the relevant files and directories.
Some files central to Arrow CI are:
diff --git a/docs/source/developers/contributing.rst
b/docs/source/developers/contributing.rst
deleted file mode 100644
index 6dc2a4e014..0000000000
--- a/docs/source/developers/contributing.rst
+++ /dev/null
@@ -1,190 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
-.. or more contributor license agreements. See the NOTICE file
-.. distributed with this work for additional information
-.. regarding copyright ownership. The ASF licenses this file
-.. to you under the Apache License, Version 2.0 (the
-.. "License"); you may not use this file except in compliance
-.. with the License. You may obtain a copy of the License at
-
-.. http://www.apache.org/licenses/LICENSE-2.0
-
-.. Unless required by applicable law or agreed to in writing,
-.. software distributed under the License is distributed on an
-.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-.. KIND, either express or implied. See the License for the
-.. specific language governing permissions and limitations
-.. under the License.
-
-.. highlight:: console
-
-.. _contributing:
-
-****************************
-Contributing to Apache Arrow
-****************************
-
-**Thanks for your interest in the Apache Arrow project.**
-
-Arrow is a large project and may seem overwhelming when you're
-first getting involved. Contributing code is great, but that's
-probably not the first place to start. There are lots of ways to
-make valuable contributions to the project and community.
-
-This page provides some orientation for how to get involved. It also offers
-some recommendations on how to get the best results when engaging with the
-community.
-
-Code of Conduct
-===============
-
-All participation in the Apache Arrow project is governed by the ASF's
-`Code of Conduct <https://www.apache.org/foundation/policies/conduct.html>`_.
-
-.. grid:: 2
- :gutter: 4
- :padding: 2 2 0 0
- :class-container: sd-text-center
-
- .. grid-item-card:: Community
- :img-top: ./images/users-solid.svg
- :class-card: contrib-card
- :shadow: md
-
- A good first step to getting involved in the Arrow project is to join
- the mailing lists and participate in discussions where you can.
-
- +++
-
- .. button-link:: https://arrow.apache.org/community/
- :click-parent:
- :color: secondary
- :expand:
-
- Apache Arrow Community
-
- .. grid-item-card:: Bug reports
- :img-top: ./images/bug-solid.svg
- :class-card: contrib-card
- :shadow: md
-
- Alerting us to unexpected behavior and missing features, even
- if you can't solve the problems yourself, help us understand
- and prioritize work to improve the libraries.
-
- +++
-
- .. button-ref:: bug-reports
- :ref-type: ref
- :click-parent:
- :color: secondary
- :expand:
-
- Bugs and Features
-
-.. dropdown:: Communicating through the mailing lists
- :animate: fade-in-slide-down
- :class-title: sd-fs-5
- :class-container: sd-shadow-md
-
- Projects in The Apache Software Foundation ("the ASF") use public, archived
- mailing lists to create a public record of each project's development
- activities and decision-making process.
-
- While lacking the immediacy of chat or other forms of communication,
- the mailing lists give participants the opportunity to slow down and be
- thoughtful in their responses, and they help developers who are spread
across
- many timezones to participate more equally.
-
- Read more on the `Apache Arrow Community
<https://arrow.apache.org/community/>`_
- page.
-
-.. dropdown:: Improve documentation
- :animate: fade-in-slide-down
- :class-title: sd-fs-5
- :class-container: sd-shadow-md
-
- A great way to contribute to the project is to improve documentation. If you
- found some docs to be incomplete or inaccurate, share your hard-earned
knowledge
- with the rest of the community.
-
- Documentation improvements are also a great way to gain some experience with
- our submission and review process, discussed below, without requiring a lot
- of local development environment setup. In fact, many documentation-only
changes
- can be made directly in the GitHub web interface by clicking the "edit"
button.
- This will handle making a fork and a pull request for you.
-
- * :ref:`documentation`
- * :ref:`building-docs`
-
-.. grid:: 2
- :gutter: 4
- :padding: 2 2 0 0
- :class-container: sd-text-center
-
- .. grid-item-card:: New Contributors
- :img-top: ./images/book-open-solid.svg
- :class-card: contrib-card
- :shadow: md
-
- First time contributing?
-
- The New Contributor's Guide provides necessary information for
- contributing to the Apache Arrow project.
-
- +++
-
- .. button-ref:: guide-introduction
- :ref-type: ref
- :click-parent:
- :color: secondary
- :expand:
-
- New Contributor's guide
-
- .. grid-item-card:: Overview
- :img-top: ./images/code-solid.svg
- :class-card: contrib-card
- :shadow: md
-
- A short overview of the contributing process we follow
- and some additional information you might need if you are not
- new to the contributing process in general.
- +++
-
- .. button-ref:: contrib-overview
- :ref-type: ref
- :click-parent:
- :color: secondary
- :expand:
-
- Contributing overview
-
-Language specific
-=================
-
-Connection to the specific language development pages:
-
-.. tab-set::
-
- .. tab-item:: C++
-
- * :ref:`cpp-development`
- * :ref:`C++ Development Guidelines <development-cpp>`
- * :ref:`building-arrow-cpp`
-
- .. tab-item:: Java
-
- * :doc:`java/index`
-
- .. tab-item:: Python
-
- * :ref:`python-development`
-
- .. tab-item:: R
-
- * `Arrow R Package: Developer environment setup
<https://arrow.apache.org/docs/dev/r/articles/developers/setup.html>`_
- * `Arrow R Package: Common developer workflow tasks
<https://arrow.apache.org/docs/dev/r/articles/developers/workflow.html>`_
-
- .. tab-item:: Ruby
-
- * `Red Arrow - Apache Arrow Ruby
<https://github.com/apache/arrow/tree/main/ruby/red-arrow#development>`_
diff --git a/docs/source/developers/images/book-open-solid.svg
b/docs/source/developers/images/book-open-solid.svg
index cbc8ed2725..9586e249be 100644
--- a/docs/source/developers/images/book-open-solid.svg
+++ b/docs/source/developers/images/book-open-solid.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 576 512"><!--! Font
Awesome Pro 6.0.0 by @fontawesome - https://fontawesome.com License -
https://fontawesome.com/license (Commercial License) Copyright 2022 Fonticons,
Inc. --><path d="M144.3 32.04C106.9 31.29 63.7 41.44 18.6 61.29c-11.42
5.026-18.6 16.67-18.6 29.15l0 357.6c0 11.55 11.99 19.55 22.45 14.65c126.3-59.14
219.8 11 223.8 14.01C249.1 478.9 252.5 480 256 480c12.4 0 16-11.38
16-15.98V80.04c0-5.203-2.531-10.08-6.781-13.08C263.3 [...]
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg"; height="1em" viewBox="0 0 576
512"><!--! Font Awesome Free 6.4.0 by @fontawesome - https://fontawesome.com
License - https://fontawesome.com/license (Commercial License) Copyright 2023
Fonticons, Inc. --><style>svg{fill:#0a7e91}</style><path d="M249.6 471.5c10.8
3.8 22.4-4.1 22.4-15.5V78.6c0-4.2-1.6-8.4-5-11C247.4 52 202.4 32 144 32C93.5 32
46.3 45.3 18.1 56.1C6.8 60.5 0 71.7 0 83.8V454.1c0 11.9 12.8 20.2 24.1
16.5C55.6 460.1 105.5 448 144 448c33.9 [...]
\ No newline at end of file
diff --git a/docs/source/developers/images/bug-solid.svg
b/docs/source/developers/images/bug-solid.svg
index f842cb2405..49cc04a1f0 100644
--- a/docs/source/developers/images/bug-solid.svg
+++ b/docs/source/developers/images/bug-solid.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 512 512"><!--! Font
Awesome Pro 6.0.0 by @fontawesome - https://fontawesome.com License -
https://fontawesome.com/license (Commercial License) Copyright 2022 Fonticons,
Inc. --><path d="M352 96V99.56C352 115.3 339.3 128 323.6 128H188.4C172.7 128
159.1 115.3 159.1 99.56V96C159.1 42.98 202.1 0 255.1 0C309 0 352 42.98 352
96zM41.37 105.4C53.87 92.88 74.13 92.88 86.63 105.4L150.6 169.4C151.3 170 151.9
170.7 152.5 171.4C166.8 164.1 182.9 16 [...]
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg"; height="1em" viewBox="0 0 512
512"><!--! Font Awesome Free 6.4.0 by @fontawesome - https://fontawesome.com
License - https://fontawesome.com/license (Commercial License) Copyright 2023
Fonticons, Inc. --><style>svg{fill:#0a7e91}</style><path d="M256 0c53 0 96 43
96 96v3.6c0 15.7-12.7 28.4-28.4 28.4H188.4c-15.7 0-28.4-12.7-28.4-28.4V96c0-53
43-96 96-96zM41.4 105.4c12.5-12.5 32.8-12.5 45.3 0l64 64c.7 .7 1.3 1.4 1.9
2.1c14.2-7.3 30.4-11.4 47.5-11.4H31 [...]
\ No newline at end of file
diff --git a/docs/source/developers/images/code-solid.svg
b/docs/source/developers/images/code-solid.svg
index 725f767148..4bbd567528 100644
--- a/docs/source/developers/images/code-solid.svg
+++ b/docs/source/developers/images/code-solid.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 640 512"><!--! Font
Awesome Pro 6.0.0 by @fontawesome - https://fontawesome.com License -
https://fontawesome.com/license (Commercial License) Copyright 2022 Fonticons,
Inc. --><path d="M414.8 40.79L286.8 488.8C281.9 505.8 264.2 515.6 247.2
510.8C230.2 505.9 220.4 488.2 225.2 471.2L353.2 23.21C358.1 6.216 375.8-3.624
392.8 1.232C409.8 6.087 419.6 23.8 414.8 40.79H414.8zM518.6 121.4L630.6
233.4C643.1 245.9 643.1 266.1 630.6 278.6L518.6 [...]
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg"; height="1em" viewBox="0 0 640
512"><!--! Font Awesome Free 6.4.0 by @fontawesome - https://fontawesome.com
License - https://fontawesome.com/license (Commercial License) Copyright 2023
Fonticons, Inc. --><style>svg{fill:#0a7c8f}</style><path d="M392.8
1.2c-17-4.9-34.7 5-39.6 22l-128 448c-4.9 17 5 34.7 22 39.6s34.7-5
39.6-22l128-448c4.9-17-5-34.7-22-39.6zm80.6 120.1c-12.5 12.5-12.5 32.8 0
45.3L562.7 256l-89.4 89.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12 [...]
\ No newline at end of file
diff --git a/docs/source/developers/images/users-solid.svg
b/docs/source/developers/images/users-solid.svg
index a04d7fe2fd..4bdf638a70 100644
--- a/docs/source/developers/images/users-solid.svg
+++ b/docs/source/developers/images/users-solid.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 640 512"><!--! Font
Awesome Pro 6.0.0 by @fontawesome - https://fontawesome.com License -
https://fontawesome.com/license (Commercial License) Copyright 2022 Fonticons,
Inc. --><path d="M319.9 320c57.41 0 103.1-46.56
103.1-104c0-57.44-46.54-104-103.1-104c-57.41 0-103.1 46.56-103.1 104C215.9
273.4 262.5 320 319.9 320zM369.9 352H270.1C191.6 352 128 411.7 128 485.3C128
500.1 140.7 512 156.4 512h327.2C499.3 512 512 500.1 512 485.3C512 411. [...]
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg"; height="1em" viewBox="0 0 640
512"><!--! Font Awesome Free 6.4.0 by @fontawesome - https://fontawesome.com
License - https://fontawesome.com/license (Commercial License) Copyright 2023
Fonticons, Inc. --><style>svg{fill:#0a788a}</style><path d="M144 0a80 80 0 1 1
0 160A80 80 0 1 1 144 0zM512 0a80 80 0 1 1 0 160A80 80 0 1 1 512 0zM0 298.7C0
239.8 47.8 192 106.7 192h42.7c15.9 0 31 3.5 44.6 9.7c-1.3 7.2-1.9 14.7-1.9
22.3c0 38.2 16.8 72.5 43.3 96c-.2 0 [...]
\ No newline at end of file
diff --git a/docs/source/developers/index.rst b/docs/source/developers/index.rst
index f6a15a6c54..c2f10c9e95 100644
--- a/docs/source/developers/index.rst
+++ b/docs/source/developers/index.rst
@@ -15,12 +15,206 @@
.. specific language governing permissions and limitations
.. under the License.
+.. highlight:: console
+
+.. _developers:
+
+Development
+===========
+
+Connection to the specific language development pages:
+
+.. tab-set::
+
+ .. tab-item:: C++
+
+ * :ref:`cpp-development`
+ * :ref:`C++ Development Guidelines <development-cpp>`
+ * :ref:`building-arrow-cpp`
+
+ .. tab-item:: Java
+
+ * :doc:`java/index`
+
+ .. tab-item:: Python
+
+ * :ref:`python-development`
+
+ .. tab-item:: R
+
+ * `Arrow R Package: Developer environment setup
<https://arrow.apache.org/docs/dev/r/articles/developers/setup.html>`_
+ * `Arrow R Package: Common developer workflow tasks
<https://arrow.apache.org/docs/dev/r/articles/developers/workflow.html>`_
+
+ .. tab-item:: Ruby
+
+ * `Red Arrow - Apache Arrow Ruby
<https://github.com/apache/arrow/tree/main/ruby/red-arrow#development>`_
+
+.. _contributing:
+
+Contributing to Apache Arrow
+============================
+
+**Thanks for your interest in the Apache Arrow project.**
+
+Arrow is a large project and may seem overwhelming when you're
+first getting involved. Contributing code is great, but that's
+probably not the first place to start. There are lots of ways to
+make valuable contributions to the project and community.
+
+This page provides some orientation for how to get involved. It also offers
+some recommendations on how to get the best results when engaging with the
+community.
+
+Code of Conduct
+---------------
+
+All participation in the Apache Arrow project is governed by the ASF's
+`Code of Conduct <https://www.apache.org/foundation/policies/conduct.html>`_.
+
+.. grid:: 2
+ :gutter: 4
+ :padding: 2 2 0 0
+ :class-container: sd-text-center
+
+ .. grid-item-card:: Apache Arrow Community
+ :img-top: ./images/users-solid.svg
+ :class-card: contrib-card
+ :shadow: none
+
+ A good first step to getting involved in the Arrow project is to join
+ the mailing lists and participate in discussions where you can.
+
+ +++
+
+ .. button-link:: https://arrow.apache.org/community/
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To Apache Arrow Community
+
+ .. grid-item-card:: Bug reports and feature requests
+ :img-top: ./images/bug-solid.svg
+ :class-card: contrib-card
+ :shadow: none
+
+ Alerting us to unexpected behavior and missing features, even
+ if you can't solve the problems yourself, help us understand
+ and prioritize work to improve the libraries.
+
+ +++
+
+ .. button-ref:: bug-reports
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To Bug reports and feature requests
+
+.. dropdown:: Communicating through the mailing lists
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-none
+
+ Projects in The Apache Software Foundation ("the ASF") use public, archived
+ mailing lists to create a public record of each project's development
+ activities and decision-making process.
+
+ While lacking the immediacy of chat or other forms of communication,
+ the mailing lists give participants the opportunity to slow down and be
+ thoughtful in their responses, and they help developers who are spread
across
+ many timezones to participate more equally.
+
+ Read more on the `Apache Arrow Community
<https://arrow.apache.org/community/>`_
+ page.
+
+.. dropdown:: Improve documentation
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+
+ A great way to contribute to the project is to improve documentation. If you
+ found some docs to be incomplete or inaccurate, share your hard-earned
knowledge
+ with the rest of the community.
+
+ Documentation improvements are also a great way to gain some experience with
+ our submission and review process, discussed below, without requiring a lot
+ of local development environment setup. In fact, many documentation-only
changes
+ can be made directly in the GitHub web interface by clicking the "edit"
button.
+ This will handle making a fork and a pull request for you.
+
+ * :ref:`documentation`
+ * :ref:`building-docs`
+
+.. grid:: 2
+ :gutter: 4
+ :padding: 2 2 0 0
+ :class-container: sd-text-center
+
+ .. grid-item-card:: New Contributor's guide
+ :img-top: ./images/book-open-solid.svg
+ :class-card: contrib-card
+
+ First time contributing?
+
+ The New Contributor's Guide provides necessary information for
+ contributing to the Apache Arrow project.
+
+ +++
+
+ .. button-ref:: guide-introduction
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the New Contributor's guide
+
+ .. grid-item-card:: Contributing Overview
+ :img-top: ./images/code-solid.svg
+ :class-card: contrib-card
+
+ A short overview of the contributing process we follow
+ and some additional information you might need if you are not
+ new to the contributing process in general.
+ +++
+
+ .. button-ref:: contrib-overview
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To Contributing overview
+
+.. dropdown:: Continuous Integration
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-none
+
+ Continuous Integration needs to run across different combinations of
package managers, compilers, versions of multiple
+ software libraries, operating systems, and other potential sources of
variation.
+
+ Read more on the :ref:`continuous_integration` page.
+
+.. dropdown:: Benchmarks
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-none
+
+ How to use the benchmark suite can be found on the :ref:`benchmarks` page.
+
+.. dropdown:: Release Guide
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-none
+
+ To learn about the detailed information on the steps followed to perform a
release, see :ref:`release`.
+
.. toctree::
:maxdepth: 2
- :caption: Development
:hidden:
- contributing
bug_reports
guide/index
overview
diff --git a/docs/source/developers/overview.rst
b/docs/source/developers/overview.rst
index 272f3dbd98..c7bc427331 100644
--- a/docs/source/developers/overview.rst
+++ b/docs/source/developers/overview.rst
@@ -45,7 +45,7 @@ checklist for using ``git``:
.. dropdown:: How to squash local commits?
:animate: fade-in-slide-down
- :class-container: sd-shadow-md
+ :class-container: sd-shadow-none
Abort the rebase with:
@@ -78,7 +78,7 @@ checklist for using ``git``:
.. dropdown:: Setting rebase to be default
:animate: fade-in-slide-down
- :class-container: sd-shadow-md
+ :class-container: sd-shadow-none
If you set the following in your repo's ``.git/config``, the ``--rebase``
option can be
omitted from the ``git pull`` command, as it is implied by default.
@@ -136,7 +136,7 @@ will merge the pull request. This is done with a
.. dropdown:: Details on squash merge
:animate: fade-in-slide-down
- :class-container: sd-shadow-md
+ :class-container: sd-shadow-none
A pull request is merged with a squash merge so that all of your commits
will be
registered as a single commit to the main branch; this simplifies the
diff --git a/docs/source/developers/release.rst
b/docs/source/developers/release.rst
index 066400b33f..6924c2d714 100644
--- a/docs/source/developers/release.rst
+++ b/docs/source/developers/release.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _release:
+
========================
Release Management Guide
========================
diff --git a/docs/source/format/index.rst b/docs/source/format/index.rst
index 1771b36d76..ae2baf128b 100644
--- a/docs/source/format/index.rst
+++ b/docs/source/format/index.rst
@@ -15,10 +15,13 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _format:
+
+Specifications and Protocols
+============================
+
.. toctree::
:maxdepth: 2
- :caption: Specifications and Protocols
- :hidden:
Versioning
Columnar
diff --git a/docs/source/index.rst b/docs/source/index.rst
index b348d3dab2..e8cdf50c5b 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+:html_theme.sidebar_secondary.remove:
+
Apache Arrow
============
@@ -35,11 +37,71 @@ such topics as:
**To learn how to use Arrow refer to the documentation specific to your
target environment.**
+.. grid:: 2
+ :gutter: 4
+ :padding: 2 2 0 0
+ :class-container: sd-text-center
+
+ .. grid-item-card:: Specifications and Protocols
+ :class-card: contrib-card
+ :shadow: none
+
+ Read about the Apache Arrow format
+ specifications and Protocols.
+
+ +++
+
+ .. button-ref:: format
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the Specifications and Protocols
+
+ .. grid-item-card:: Development
+ :class-card: contrib-card
+ :shadow: none
+
+ Find the documentation on the topic of
+ contributions, reviews, building of the libraries
+ from source, building of the documentation,
+ continuous integration, benchmarks and the
+ release process.
+
+ +++
+
+ .. button-ref:: developers
+ :ref-type: ref
+ :click-parent:
+ :color: primary
+ :expand:
+
+ To the Development
+
+.. _toc.columnar:
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ format/index
+
+.. _toc.development:
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ developers/index
+
+Implementations
+---------------
+
.. _toc.usage:
.. toctree::
:maxdepth: 1
- :caption: Supported Environments
C/GLib <c_glib/index>
C++ <cpp/index>
@@ -55,52 +117,15 @@ target environment.**
Rust <https://docs.rs/crate/arrow/>
status
+Examples
+--------
+
.. _toc.cookbook:
.. toctree::
:maxdepth: 1
- :caption: Cookbooks
-
- C++ <https://arrow.apache.org/cookbook/cpp/>
- Java <https://arrow.apache.org/cookbook/java/>
- Python <https://arrow.apache.org/cookbook/py/>
- R <https://arrow.apache.org/cookbook/r/>
-.. _toc.columnar:
-
-.. toctree::
- :maxdepth: 2
- :caption: Specifications and Protocols
-
- format/Versioning
- format/Columnar
- format/CanonicalExtensions
- format/Flight
- format/FlightSql
- format/Integration
- format/CDataInterface
- format/CStreamInterface
- format/CDeviceDataInterface
- format/ADBC
- format/Other
- format/Changing
- format/Glossary
-
-.. _toc.development:
-
-.. toctree::
- :maxdepth: 2
- :caption: Development
-
- developers/contributing
- developers/bug_reports
- developers/guide/index
- developers/overview
- developers/reviewing
- developers/cpp/index
- developers/java/index
- developers/python
- developers/continuous_integration/index
- developers/benchmarks
- developers/documentation
- developers/release
+ C++ cookbook <https://arrow.apache.org/cookbook/cpp/>
+ Java cookbook <https://arrow.apache.org/cookbook/java/>
+ Python cookbook <https://arrow.apache.org/cookbook/py/>
+ R cookbook <https://arrow.apache.org/cookbook/r/>
diff --git a/docs/source/java/index.rst b/docs/source/java/index.rst
index 9b555e297b..cf93b0e897 100644
--- a/docs/source/java/index.rst
+++ b/docs/source/java/index.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _java:
+
Java Implementation
===================
@@ -41,3 +43,4 @@ on the Arrow format and other language bindings see the
:doc:`parent documentati
cdata
jdbc
Reference (javadoc) <reference/index>
+ Java cookbook <https://arrow.apache.org/cookbook/java/>
diff --git a/docs/source/js/index.rst b/docs/source/js/index.rst
index 77813c1372..2ab205a08b 100644
--- a/docs/source/js/index.rst
+++ b/docs/source/js/index.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _js:
+
JavaScript docs
===============
diff --git a/docs/source/python/index.rst b/docs/source/python/index.rst
index b80cbc7de5..6a3de3d42b 100644
--- a/docs/source/python/index.rst
+++ b/docs/source/python/index.rst
@@ -15,8 +15,13 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _python:
+
+Python
+======
+
PyArrow - Apache Arrow Python bindings
-======================================
+--------------------------------------
This is the documentation of the Python API of Apache Arrow.
@@ -62,3 +67,4 @@ files into Arrow structures.
api
getting_involved
benchmarks
+ Python cookbook <https://arrow.apache.org/cookbook/py/>
diff --git a/docs/source/r/index.rst b/docs/source/r/index.rst
index b799544bb6..8ccbec132a 100644
--- a/docs/source/r/index.rst
+++ b/docs/source/r/index.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _r:
+
R docs
======
