Documentation reorg / edit suggestions + recommend use_pkgdown_github_pages() over use_pkgdown()

[olivroy]

Addresses partly #2560.

The goal is to have a consistent way to access how each component of _pkgdown.yml can be customized.

• Join init_site() and build_favicons() docs. For consistency, build_favicons() should probably be init_favicons()?
• Add a couple of references throughout. (some things are now very well documented in https://r-pkgs.org, so it'd be worth adding couple references to that!)

I tried gathering as much info as possible of potential allowed yaml config and create a menu item. (I didn't commit this, but here is what I have so far). (It would be great to have yaml validation in RStudio like we have with _quarto.yml for _pkgdown.yml, but that's probably a long shot.

From my findings, the info is all present, but is scattered between customize.Rmd, pkgdown.Rmd, build_site() and the different build_*() functions.

navbar:
  structure:
    left: [intro, reference, articles, parts, news]
  components:
    parts:
      text: "Components of _pkgdown.yml"
      menu:
      - text: "Overview"
        href: reference/build_site.html#general-config
      - text: "-----"
      - text: "reference: (Package index)"
        href: reference/build_reference.html#reference-index
      - text: "figures: (How figures are rendered)"
        href: reference/build_reference.html#figures
      - text: "navbar: (Menus + components)"
        href: articles/customise.html#navbar-heading
      - text: "home (Homepage customization)"
        href: reference/build_home.html
      - text: "template: (Site theme and customisation)"
        href: '`vignette("customise")`'
      - text: "redirects: (Link redirects)"
        href: reference/build_redirects.html
      - text: "development: (Development mode)"
        href: reference/build_site.html#development-mode
      - text: "search: (Search functions)"
        href: reference/build_search.html
      - text: "news: (Changelog + release blog post)"
        href: reference/build_news.html
      - text: "lang: (Change the language)"
        href: articles/translations.html
      - text: "footer: (Personalize footer)"
        href: articles/customise.html#footer
      - text: "url:, destination:, title: (General Config)"
        href: reference/build_home.html#general-config
      - text: "repo: (Source repository)"
        href: reference/build_site.html#source-repository
      - text: "---"
      - text: "Examples"
        href: index.html#in-the-wild
      - text: "---"
      - text: "Template for articles or reference index examples"
        href: reference/templates.html

Preview:

[hadley]

Thanks for working on this! A bunch of smaller comments below.

[hadley]

I agree that build_favicons() is probably better as init_favicons() since it does imply that you don't need to run it very often. But I think you're likely to run it even less than init_site() (and indeed in most cases pkgdown will run it for you) so I think documenting with init_site() makes it maybe a bit too prominent.

[hadley]

Feel free to merge whenever you're ready 😄

[olivroy]

@hadley I ended up pushing extra changes . f3cf62b and 8f3a286

• Typo fix has_keywords() -> has_keyword(), pr_submit() -> pr_push()
• Avoid mentioning Rbuildignore in the pkgdown documentation
• Rephrase the favicons topic and move it down to helpers in function organization.
• Add a redirect from the language section in the pkgdown.Rmd vignette to the new translations vignette
• Add @family to build_home(), build_articles(), build_news(), and build_reference() for 2 reasons
  1. Add cross-refs between these topics. (I tried to rename topics to home, articles, news, and reference, but ran into a roxygen2 issue. (I will try providing a reprex there)
  2. Be able to use has_concept() in _pkgdown.yml. I think it is an underused / underadvertised feature, because it allows organizing your docs in R itself + pkgdown (instead of having to do it twice) What better way to learn about pkgdown than to look at pkgdown's _pkgdown.yml itself!

I will request a new review since these changes are substantial (and may be a question of preference)

[hadley]

Suggested change

	If you want to include an article on the website but not in the package (e.g., because it's large), you can either place it in a subdirectory of `vignettes/` (e.g. `vignettes/web_only`) or add it to `.Rbuildignore` (and make sure that there's no `vignettes:` section in the yaml header). See `usethis::use_article()` for an automated way to do this.
	If you want to include an article on the website but not in the package (e.g., because it's large), you can either place it in a subdirectory of `vignettes/` (e.g. `vignettes/articles`) or add it to `.Rbuildignore` (and make sure that there's no `vignettes:` section in the yaml header). See `usethis::use_article()` for an automated way to do this.

Do we really need to suggest two ways to do this?

[hadley]

Since we're now only recommending one way (which is good!), this sentence needs to be tweaked, and I think we can get rid of the bullets.

[olivroy]

I also made changes in README to reflect that everywhere!

[hadley]

LGTM!

[olivroy]

@hadley do you want to take one final look as I made tweaks to vignette and README in c2a6389 to make the use_pkgdown_github_pages() advice more prominent everywhere?