ARROW-17887: [R][Doc] Improve readability of the Get Started and README pages

[djnavarro]

This pull request proposes a number of changes to the pkgdown site for the R package:

• Reduces the content on the README page to the essential points
• Rewrites the "get started" page to focus on common tasks and novice users
• Moves discussion of the Arrow data object hierarchy to a new "data objects" vignette
• Moves discussion of Arrow data types and conversions to a new "data types" vignette
• Moves discussion of schemas and storage of R attributes to a new "metadata" vignette
• Moves discussion of package naming conventions to a new "package conventions" vignette
• Moves discussion of read/write capabilities to a new "reading and writing data" vignette
• Moves discussion of the dplyr back end to a new "data wrangling" vignette
• Edits the "multi-file data sets" vignette to improve readability and to minimize risk of novice users unintentionally downloading the 70GB NYC taxi data by copy/paste errors
• Minor edits to the "python" vignette to improve readability
• Minor edits to the "cloud storage" vignette to improve readability
• Minor edits to the "flight" vignette to improve readability
• Inserts a new "data object layout" vignette (in the developer vignettes) to bridge between the R documentation and the Arrow specification page

In addition there are some structural changes:

• The pkgdown template now uses bootstrap 5
• The articles menu organizes the vignettes into meaningful categories
• The former "project docs" menu has been replaced with a sidebar on the main page
• Some vignette filenames have been edited and links updated (this has been reverted)
• The developer vignettes are now in the main vignettes folder (this has been reverted)

Possible issues as yet unaddressed:

• I have not yet checked whether the bootstrap 5 template breaks the script inserting the documentation versions switcher
• Changes to developer vignettes are extremely minimal in comparison to other vignettes. I'm uncertain whether to make further changes there or to defer that to a later PR
• The "articles" menu currently hides all the developer vignettes under the "more articles" link: they should be made more prominent and easy to find
• Some topics may not be described as well as we'd like?
• The proposed edits to the vignettes include a lot more code that is executed at build time. This may not be desirable?

[djnavarro]

okay so we might be ready to merge this? I'm running out of things that I want to try fixing in this iteration of improvements

[thisisnic]

I've removed the WIP flag from the issue title to run the CI on it.

I'm happy to give the contents a thumbs up and defer any more changes to follow-up tickets.

Before I approve it, I'm going to pull it locally and build it there just to give it a final look over all together.

@nealrichardson - did you want to give this a look over as well?

[thisisnic]

I've built this locally and it looks good!

Thanks for your hard work on this @djnavarro! This is a significant contribution and makes a lot of things clearer for users.

One small note - it was my error as a maintainer to not insist on splitting up this PR into a series of smaller PRs; though I see why it made sense to do it all in one here given content is being moved between sections, in practice it's been a bit tricky to keep up with what has or hasn't been reviewed, and it also can make it tricky for anyone who wants to later look at the source of a change. Please can you split changes up into smaller PRs on future contributions?

The upgrade to Bootstrap 5 will break the version dropdown selector, but I've opened ARROW-18391 to fix it, and will look at that myself shortly.

[stephhazlitt]

One thing I noticed, which might be worth a follow up ticket (or maybe I am being too picky) -- in the Articles drop down menu readers can no longer see that there are Developer guides articles. A user needs a second click through More articles... and then scroll a distance. I wonder if the drop down can be tailored a bit to show the categories at first glance?

[thisisnic]

I approved this before the CI had run, but there are a few failures relating to linting that need to be sorted before we merge.

[djnavarro]

@thisisnic I think all the linting issues are now fixed. And yes, I agree this PR is too big to review easily: I'll work harder at splitting into separate PRs in future 🙂

[djnavarro]

@stephhazlitt Yeah I noticed that issue with the developer vignettes earlier. It would be nice if we could have a menu item that linked to that subsection of the articles page. That way devs would be able to click through with about the same level of ease as they have under the current docs where dev vignettes are tucked into a submenu. I haven't quite worked out how to do that with the bootstrap5 pkgdown templates yet. Tempted to push that to a separate PR 😁

[stephhazlitt]

+1 for sure for pushing that into a subsequent ticket/PR @djnavarro. Great, great work on this PR.

[ursabot]

Benchmark runs are scheduled for baseline = 409a95d and contender = 4afe710. 4afe710 is a master commit associated with this PR. Results will be available as each benchmark for each run completes.
Conbench compare runs links:
[Finished ⬇️0.0% ⬆️0.0%] ec2-t3-xlarge-us-east-2
[Failed ⬇️0.13% ⬆️4.06%] test-mac-arm
[Finished ⬇️0.0% ⬆️0.0%] ursa-i9-9960x
[Finished ⬇️0.28% ⬆️0.42%] ursa-thinkcentre-m75q
Buildkite builds:
[Finished] 4afe7103 ec2-t3-xlarge-us-east-2
[Failed] 4afe7103 test-mac-arm
[Finished] 4afe7103 ursa-i9-9960x
[Finished] 4afe7103 ursa-thinkcentre-m75q
[Finished] 409a95dd ec2-t3-xlarge-us-east-2
[Finished] 409a95dd test-mac-arm
[Finished] 409a95dd ursa-i9-9960x
[Finished] 409a95dd ursa-thinkcentre-m75q
Supported benchmarks:
ec2-t3-xlarge-us-east-2: Supported benchmark langs: Python, R. Runs only benchmarks with cloud = True
test-mac-arm: Supported benchmark langs: C++, Python, R
ursa-i9-9960x: Supported benchmark langs: Python, R, JavaScript
ursa-thinkcentre-m75q: Supported benchmark langs: C++, Java