Skip to content

Commit

Permalink
GH-36590: [Docs] Support Pydata Sphinx Theme 0.14.0 (#36591)
Browse files Browse the repository at this point in the history 
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]>
  • Loading branch information
@AlenkaF @kou
AlenkaF and kou authored Sep 27, 2023
1 parent e038498 commit 7dc9f69
Show file tree
Hide file tree
Showing 31 changed files with 416 additions and 472 deletions.
2 changes: 1 addition & 1 deletion ci/conda_env_sphinx.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ breathe
doxygen
ipython
numpydoc
pydata-sphinx-theme==0.8
pydata-sphinx-theme
sphinx-autobuild
sphinx-design
sphinx-copybutton
Expand Down
3 changes: 2 additions & 1 deletion dev/release/01-prepare-test.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,8 @@ def test_version_pre_tag
"+ \"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}/\"",
"+ },",
],
],
Expand Down
3 changes: 2 additions & 1 deletion dev/release/post-11-bump-versions-test.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,8 @@ def test_version_post_tag
"+ \"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}/\"",
"+ },",
],
],
Expand Down
10 changes: 7 additions & 3 deletions dev/release/utils-update-docs-versions.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,11 +50,15 @@
# 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:
Expand Down
3 changes: 1 addition & 2 deletions docs/requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Binary file added docs/source/_static/arrow-dark.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
85 changes: 6 additions & 79 deletions docs/source/_static/theme_overrides.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
}

Expand Down Expand Up @@ -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;
}
}
47 changes: 29 additions & 18 deletions docs/source/_static/versions.json
View file
Original file line number Diff line number Diff line change
@@ -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/"
}
]
2 changes: 2 additions & 0 deletions docs/source/_static/versionwarning.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)","");
Expand Down
25 changes: 0 additions & 25 deletions docs/source/_templates/docs-sidebar.html
View file

This file was deleted.

10 changes: 0 additions & 10 deletions docs/source/_templates/layout.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
60 changes: 0 additions & 60 deletions docs/source/_templates/version-switcher.html
View file

This file was deleted.

2 changes: 2 additions & 0 deletions docs/source/c_glib/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
.. _c-glib:

C/GLib docs
===========

Expand Down
Loading

0 comments on commit 7dc9f69

Please sign in to comment.