Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: add optional per version url in version-switcher #575

Merged
merged 3 commits into from
Feb 8, 2022
Merged

ENH: add optional per version url in version-switcher #575

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cdb4295
ENH: add optional per version url in version-switcher
tupui Jan 20, 2022
6498881
DOC: add url in one example
tupui Jan 25, 2022
950ee26
Update docs/user_guide/configuring.rst
tupui Feb 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions docs/user_guide/configuring.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -378,14 +378,16 @@ 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
also checked against ``switcher['version_match']`` to provide styling to the
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``
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add an example of this usage in one of the entries in the example below, with a comment like "Note that because url is specified for entry XXX, this URL will be used instead of the automatically-generated one."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added it in an example. But since it's a JSON file I cannot really add a comment no??

instead of ``switcher['url_template']``.

Here is an example JSON file:

Expand All @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down