From 052a7faf4eb0764a0c9f2bbdea6543ab9ee30e69 Mon Sep 17 00:00:00 2001 From: Pamphile Roy Date: Tue, 8 Feb 2022 20:31:18 +0100 Subject: [PATCH] ENH: add optional per version url in version-switcher (#575) Co-authored-by: Chris Holdgraf --- docs/user_guide/configuring.rst | 9 ++++++--- .../pydata_sphinx_theme/_templates/version-switcher.html | 4 +++- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index f1196869e..56f4e41d0 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -378,7 +378,7 @@ Add a JSON file to define your switcher's versions First, write a JSON file stating which versions of your docs will be listed in the switcher's dropdown menu. That file should contain a list of entries that -each have one or two fields: +each can have the following fields: - ``version``: a version string. This will be inserted into ``switcher['url_template']`` to create the links to other docs versions, and @@ -386,6 +386,8 @@ each have one or two fields: switcher. - ``name``: an optional name to display in the switcher dropdown instead of the version string (e.g., "latest", "stable", "dev", etc). +- ``url``: an optional URL. If provided, it links the version to ``url`` + instead of ``switcher['url_template']``. Here is an example JSON file: @@ -400,8 +402,9 @@ Here is an example JSON file: "version": "2.0" }, { - "version": "1.0" - }, + "version": "1.0", + "url": "https://mysite.org/en/1.0/index.html" + } ] See the discussion of ``switcher['json_url']`` (below) for options of where to diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html index 10d6b75d5..9f310f7b4 100644 --- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html +++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html @@ -58,7 +58,9 @@ node.textContent = `${entry.name}`; // get the base URL for that doc version, add the current page's // path to it, and set as `href` - entry.url = buildURL(entry); + if (!("url" in entry)) { + entry.url = buildURL(entry); + } node.setAttribute("href", `${entry.url}${currentFilePath}`); // on click, AJAX calls will check if the linked page exists before // trying to redirect, and if not, will redirect to the homepage