[jira] (ARROW-14338) [Docs] Add version dropdown to the pkgdown (R) docs

["Nicola Crane (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/ARROW-14338 ]


    Nicola Crane deleted comment on ARROW-14338:
    --------------------------------------

was (Author: thisisnic):
I've had a think about this this morning and there are a few complications.  I would have liked to have done it via [~icook]'s suggestion of swapping the version for a dropdown, but given the URL refers to a major version, but the R package version displayed can be the latest minor or patch version, it means there isn't a direct mapping between these.  I was thinking to use the version button originally displayed on the page as a placeholder for the dropdown and then allow users to select the major version via the dropdown options, but the placeholder is controlled by a HTML attribute (i.e. text) and I can't work out how to replace it with a HTML element (i.e. the current button).

At this point it seems like it'd make more sense to choose the simpler option of allowing version switching via the dropdown menus specified in {{_pkgdown.yml.  }}I suppose I _could_ hack something together to force the "version button dropdown" approach mentioned earlier to work (anything's possible with JS, right?) but I'm not sure the benefit from doing so is worth the additional complexity (and likely very hacky code I'll write!).

If there are any benefits to doing it that way I haven't realised, let me know and I'll reconsider!

> [Docs] Add version dropdown to the pkgdown (R) docs
> ---------------------------------------------------
>
>                 Key: ARROW-14338
>                 URL: https://issues.apache.org/jira/browse/ARROW-14338
>             Project: Apache Arrow
>          Issue Type: Sub-task
>          Components: Documentation, R
>            Reporter: Nicola Crane
>            Assignee: Nicola Crane
>            Priority: Major
>
> The Python and C++ documentation have support for serving multiple versions of the docs and switching between them thanks to the newly added version switcher. The same doesn't apply to the R docs as they are not implemented in Sphinx and thus can't benefit from the version switcher implemented for Sphinx.
> We should provide an equivalent version switcher for the R docs.
> We are already hosting multiple versions of the R docs:
>  * Stable: [https://arrow.apache.org/docs/r/]
>  * Dev: [https://arrow.apache.org/docs/dev/r/]
>  * Old releases: [https://arrow.apache.org/docs/5.0/r/] etc.
> So the need is simply for a UI element to enable users to easily navigate between these.
> Relevant pkgdown issue: [https://github.com/r-lib/pkgdown/issues/1373]
> Possible implementation ideas:
>  - [https://insightsengineering.github.io/r.pkg.template/] does it with a dropdown in the main header, I suppose that's something we could do as well (although that would be some manual work to update it in {{_pkgdown.yml}} before each version)
>  - from [~icook]: I don’t have an example of extra.js being used specifically for version switching, but we already have an extra.js we’re using for a different purpose: [https://github.com/apache/arrow/blob/master/r/pkgdown/extra.js]. I believe it would be relatively straightforward to use jQuery to replace the static version {{<span>}} which looks like this
> {code:java}
> <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="" data-original-title="Released version">6.0.1</span>{code}
> with a {{<select>}} that would allow users to navigate to other versions of the R docs
> If it is necessary to hard-code R package versions in a file to achieve this, then we could automate the updating of these hard-coded versions at each release through [dev/release/01-prepare.sh|https://github.com/ianmcook/arrow/blob/master/dev/release/01-prepare.sh], and add a test confirming the update at [dev/release/01-prepare-test.rb|https://github.com/apache/arrow/blob/master/dev/release/01-prepare-test.rb].



--
This message was sent by Atlassian Jira
(v8.20.1#820001)