This is an automated email from the ASF dual-hosted git repository. kszucs pushed a commit to branch maint-6.0.x in repository https://gitbox.apache.org/repos/asf/arrow.git
commit 2f1300764f2d5ed7695dae816e0a2cb352830c31 Author: Joris Van den Bossche <[email protected]> AuthorDate: Wed Oct 27 16:41:57 2021 +0200 ARROW-14189: [Docs] Add version dropdown to the sphinx docs Closes #11283 from jorisvandenbossche/ARROW-14189-version-dropdown Authored-by: Joris Van den Bossche <[email protected]> Signed-off-by: Krisztián Szűcs <[email protected]> --- docs/source/_static/versions.json | 26 ++++++++++++ docs/source/_templates/docs-sidebar.html | 2 + docs/source/_templates/version-switcher.html | 60 ++++++++++++++++++++++++++++ docs/source/conf.py | 10 +++++ 4 files changed, 98 insertions(+) diff --git a/docs/source/_static/versions.json b/docs/source/_static/versions.json new file mode 100644 index 0000000..d364cfe --- /dev/null +++ b/docs/source/_static/versions.json @@ -0,0 +1,26 @@ +[ + { + "name": "6.0 (stable)", + "version": "" + }, + { + "name": "5.0", + "version": "5.0/" + }, + { + "name": "4.0", + "version": "4.0/" + }, + { + "name": "3.0", + "version": "3.0/" + }, + { + "name": "2.0", + "version": "2.0/" + }, + { + "name": "1.0", + "version": "1.0/" + } +] \ No newline at end of file diff --git a/docs/source/_templates/docs-sidebar.html b/docs/source/_templates/docs-sidebar.html index f6ee66c..9ae2e19 100644 --- a/docs/source/_templates/docs-sidebar.html +++ b/docs/source/_templates/docs-sidebar.html @@ -3,6 +3,8 @@ <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo"> </a> +{% include "version-switcher.html" %} + <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" > diff --git a/docs/source/_templates/version-switcher.html b/docs/source/_templates/version-switcher.html new file mode 100644 index 0000000..297a2b0 --- /dev/null +++ b/docs/source/_templates/version-switcher.html @@ -0,0 +1,60 @@ +<div 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/conf.py b/docs/source/conf.py index 2e5f9b5..150cd41 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -127,6 +127,9 @@ version = os.environ.get('ARROW_DOCS_VERSION', release = os.environ.get('ARROW_DOCS_VERSION', pyarrow.__version__) +if "+" in release: + release = release.split(".dev")[0] + " (dev)" + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -196,6 +199,13 @@ html_theme_options = { "google_analytics_id": "UA-107500873-1", } +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}";, +} + # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = []
