Eliminate use of child docs in documentation

R/build-home.R

@@ -14,15 +14,278 @@
 #' `build_home_index()` rebuilds just the index page; it's useful for rapidly
 #' iterating when experimenting with site styles.
 #'
-#' ```{r child="man/rmd-fragments/home-configuration.Rmd"}
+#' # Home page
+#' 
+#' The main content of the home page (`index.html`) is generated from
+#' `pkgdown/index.md`, `index.md`, or `README.md`, in that order.
+#' Most packages will use `README.md` because that's also displayed by GitHub 
+#' and CRAN. Use `index.md` if you want your package website to look 
+#' different to your README, and use `pkgdown/index.md` if you don't want that 
+#' file to live in your package root directory.
+#' 
+#' If you use `index.Rmd` or `README.Rmd` it's your responsibility to knit 
+#' the document to create the corresponding `.md`. pkgdown does not do this 
+#' for you because it only touches files in the `doc/` directory.
+#' 
+#' Extra markdown files in the base directory (e.g. `ROADMAP.md`) or in 
+#' `.github/` (e.g. `CODE_OF_CONDUCT.md`) are copied by `build_home()` to `docs/` and converted to HTML.
+#' 
+#' The home page also features a sidebar with information extracted from the 
+#' package. You can tweak it via the configuration file, to help make the home 
+#' page an as informative as possible landing page.
+#' 
+#' ## Images and figures
+#' 
+#' If you want to include images in your `README.md`, they must be stored 
+#' somewhere in the package so that they can be displayed on the CRAN website.
+#' The best place to put them is `man/figures`. If you are generating figures 
+#' with R Markdown, make sure you set up `fig.path` as followed:
+#' 
+#' ``` r
+#' knitr::opts_chunk$set(
+#'   fig.path = "man/figures/"
+#' )
 #' ```
-#' ```{r child="man/rmd-fragments/authors-configuration.Rmd"}
+#' 
+#' This should usually go in a chunk with `include = FALSE`.
+#' 
+#' ```` markdown
+#' ```{r chunk-name, include=FALSE}`r ''`
+#' knitr::opts_chunk$set(
+#'   fig.path = "man/figures/"
+#' )
 #' ```
-#'
-#' @section Sidebar:
-#' ```{r child="man/rmd-fragments/sidebar-configuration.Rmd"}
+#' ````
+#' 
+#' ## Package logo
+#' 
+#' If you have a package logo, you can include it at the top of your README
+#' in a level-one heading:
+#' 
+#' ``` markdown
+#' # pkgdown <img src="man/figures/logo.png" align="right" />
+#' ```
+#' 
+#' [init_site()] will also automatically create a favicon set from your package logo.
+#' 
+#' ## YAML config - home
+#' 
+#' To tweak the home page, you need a section of the configuration file called 
+#' `home`.
+#' 
+#' ### Page title and description
+#' 
+#' By default, the page title and description are extracted automatically from
+#' the `Title` and `Description` fields `DESCRIPTION` (stripping single quotes
+#' off quoted words). CRAN ensures that these fields don't contain phrases 
+#' like "R package" because that's obvious on CRAN. To make your package more 
+#' findable on search engines, it's good practice to override the `title` and 
+#' `description`, thinking about what people might search for:
+#' 
+#' ```yaml
+#' home:
+#'   title: An R package for pool-noodle discovery
+#'   description: >
+#'     Do you love R? Do you love pool-noodles? If so, you might enjoy
+#'     using this package to automatically discover and add pool-noodles
+#'     to your growing collection.
+#' ```
+#' 
+#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.)
+#' 
+#' ## Dev badges
+#' 
+#' pkgdown identifies badges in three ways:
+#' 
+#' -   Any image-containing links between `<!-- badges: start -->` and 
+#'     `<!-- badges: end -->`, as e.g. created by `usethis::use_readme_md()` 
+#'     or `usethis::use_readme_rmd()`. There should always be an empty line after 
+#'     the `<!-- badges: end -->` line. If you divide badges into paragraphs, 
+#'     make sure to add an empty line before the `<!-- badges: end -->` line.
+#' 
+#' -   Any image-containing links within `<div id="badges"></div>`.
+#' 
+#' -   Within the first paragraph, if it only contains image-containing links.
+#' 
+#' Identified badges are **removed** from the _main content_.
+#' They are shown or not in the _sidebar_ depending on the development mode and
+#' sidebar customization, see the sidebar section.
+#' 
+#' # Authors
+#' 
+#' By default, pkgdown will display author information in three places:
+#' 
+#' * the sidebar,
+#' * the left part side of the footer,
+#' * the author page.
+#' 
+#' This documentation describes how to customise the overall author display. 
+#' See `?build_home` and `?build_site` for details about changing the location 
+#' of the authors information within the home sidebar and the site footer.
+#' 
+#' ## Authors ORCID and bio
+#' 
+#' Author ORCID identification numbers in the `DESCRIPTION` are linked using 
+#' the ORCID logo:
+#' 
+#' ```r
+#' Authors@R: c(
+#'     person("Hadley", "Wickham", , "[email protected]", role = c("aut", "cre"),
+#'       comment = c(ORCID = "0000-0003-4757-117X")
+#'     ),
+#'     person("Jay", "Hesselberth", role = "aut",
+#'       comment = c(ORCID = "0000-0002-6299-179X")
+#'     )
+#'   )
+#' ```
+#' 
+#' If you want to add more details about authors or their involvement with the 
+#' package, you can use the comment field, which will be rendered on the 
+#' authors page.
+#' 
+#' ```r
+#' Authors@R: c(
+#'     person("Hadley", "Wickham", , "[email protected]", role = c("aut", "cre"),
+#'       comment = c(ORCID = "0000-0003-4757-117X", "Indenter-in-chief")
+#'     ),
+#'     person("Jay", "Hesselberth", role = "aut",
+#'       comment = c(ORCID = "0000-0002-6299-179X")
+#'     )
+#'   )
+#' ```
+#' 
+#' ## YAML config - authors
+#' 
+#' You can tweak a few things via the `authors` YAML field:
+#' 
+#' * display of each author in the footer, sidebar and authors page,
+#' * which authors (by role) are displayed in the sidebar and footer,
+#' * text before authors in the footer, 
+#' * text before and after authors in the sidebar,
+#' * text before and after authors on the authors page.
+#' 
+#' 
+#' You can modify how each author's name is displayed by adding a subsection 
+#' for `authors`. Each entry in `authors` should be named the author's name 
+#' (matching `DESCRIPTION`) and can contain `href` and/or `html` fields:
+#' 
+#' * If `href` is provided, the author's name will be linked to this URL.
+#' * If `html` is provided, it will be shown instead of the author's name.
+#'   This is particularly useful if you want to display the logo of a corporate
+#'   sponsor. Use an absolute URL to an image, not a relative link. Use an empty 
+#'   alternative text rather than no alternative text so a screen-reader would 
+#' skip over it.
+#' 
+#' ```yaml
+#' authors:
+#'   firstname lastname:
+#'     href: "http://name-website.com"
+#'     html: "<img src='https://website.com/name-picture.png' width=72 alt=''>"
+#' ```
+#' 
+#' 
+#' By default, the "developers" list shown in the sidebar and footer is 
+#' populated by the maintainer ("cre"), authors ("aut"), and funder ("fnd") 
+#' from the `DESCRIPTION`. You could choose other roles for filtering.
+#' With the configuration below:
+#' 
+#' * only the maintainer and funder(s) appear in the footer, after the text 
+#'   "Crafted by",
+#' * all authors and contributors appear in the sidebar,
+#' * the authors list on the sidebar is preceded and followed by some text,
+#' * the authors list on the authors page is preceded and followed by some text.
+#' 
+#' 
+#' ```yaml
+#' authors:
+#'   footer:
+#'     roles: [cre, fnd]
+#'     text: "Crafted by"
+#'   sidebar:
+#'     roles: [aut, ctb]
+#'     before: "So *who* does the work?"
+#'     after: "Thanks all!"
+#'   before: "This package is proudly brought to you by:"
+#'   after: "See the [changelog](news/index.html) for other contributors. :pray:"
+#' ```
+#' 
+#' If you want to filter authors based on something else than their roles, 
+#' consider using a custom sidebar/footer component 
+#' (see `?build_home`/`?build_site`, respectively).
+#' 
+#' # Sidebar
+#' 
+#' You can customise the homepage sidebar with the `home.sidebar` field.
+#' It's made up of two pieces: `structure`, which defines the overall layout, 
+#' and `components`, which defines what each piece looks like. This organisation 
+#' makes it easy to mix and match the pkgdown defaults with your own 
+#' customisations.
+#' 
+#' This is the default structure:
+#' 
+#' ``` yaml
+#' home:
+#'   sidebar:
+#'     structure: [links, license, community, citation, authors, dev]
+#' ```
+#' 
+#' These are drawn from seven built-in components:
+#' 
+#' -   `links`: automated links generated from `URL` and `BugReports` fields 
+#'     from `DESCRIPTION` plus manual links from the `home.links` field:
+#' 
+#'     ``` yaml
+#'     home:
+#'       links:
+#'       - text: Link text
+#'         href: https://website.com
+#'       - text: Roadmap
+#'         href: /roadmap.html
+#'     ```
+#' 
+#' -   `license`: Licensing information if `LICENSE`/`LICENCE` or 
+#'     `LICENSE.md`/`LICENCE.md` files are present.
+#' 
+#' -   `community`: links to to `.github/CONTRIBUTING.md`, 
+#'     `.github/CODE_OF_CONDUCT.md`, etc.
+#' 
+#' -   `citation`: link to package citation information. Uses either 
+#'     `inst/CITATION` or, if absent, information from the `DESCRIPTION`.
+#' 
+#' -   `authors`: selected authors from the `DESCRIPTION`.
+#' 
+#' -   `dev`: development status badges extracted from `README.md`/`index.md`. 
+#'     This is only shown for "development" versions of websites; see 
+#'     "Development mode" in `?build_site` for details. 
+#' 
+#' -   `toc`: a table of contents for the README (not shown by default).
+#' 
+#' You can also add your own components, where `text` is markdown text:
+#' 
+#' ``` yaml
+#' home:
+#'   sidebar:
+#'     structure: [authors, custom, toc, dev]
+#'     components:
+#'       custom:
+#'         title: Funding
+#'         text: We are *grateful* for funding!
+#' ```
+#' 
+#' Alternatively, you can provide a ready-made sidebar HTML:
+#' 
+#' ``` yaml
+#' home:
+#'   sidebar:
+#'     html: path-to-sidebar.html
+#' ```
+#' 
+#' Or completely remove it:
+#' 
+#' ``` yaml
+#' home:
+#'   sidebar: FALSE
 #' ```
-#'
 #' @inheritParams build_articles
 #' @export
 build_home <- function(pkg = ".",

R/build.R

@@ -14,7 +14,7 @@
 #' that aspect of the site. This page documents options that affect the
 #' whole site.
 #'
-#' @section General config:
+#' # General config
 #' *  `destination` controls where the site will be generated, defaulting to
 #'    `docs/`. Paths are relative to the package root.
 #'
@@ -33,6 +33,17 @@
 #' *  `title` overrides the default site title, which is the package name.
 #'    It's used in the page title and default navbar.
 #'
+#' # Navbar and footer
+#'
+#' The `navbar` and `footer` fields control the appearance of the navbar
+#' footer which appear on every page. Learn more about these fields in 
+#' `vignette("customise")`.
+#'
+#' # Search
+#'
+#' The `search` field controls the built-in search and is
+#' documented in `vignette("search")`.
+#'
 #' @section Development mode:
 #' The `development` field allows you to generate different sites for the
 #' development and released versions of your package. To use it, you first
@@ -122,17 +133,6 @@
 #' to danger). Finally, you can choose to override the default tooltip with
 #' `version_tooltip`.
 #'
-#' ## Page layout
-#'
-#' The `navbar`, `footer`, and `sidebar` fields control the appearance
-#' of the navbar, footer, and sidebar respectively. They have many individual
-#' options which are documented in the **Layout** section of
-#' `vignette("customise")`.
-#'
-#' @section Search:
-#' The `search` field controls the built-in search and is
-#' documented in `vignette("search")`.
-#'
 #' @section Template:
 #' The `template` field is mostly used to control the appearance of the site.
 #' See `vignette("customise")` for details.
@@ -275,8 +275,25 @@
 #'    ```
 #'
 #' @section Redirects:
-#' ```{r child="man/rmd-fragments/redirects-configuration.Rmd"}
+#' If you change the structure of your documentation (by renaming vignettes or 
+#' help topics) you can setup redirects from the old content to the new content.
+#' One or several now-absent pages can be redirected to a new page (or to a new 
+#' section of a new page). This works by creating a html page that performs a 
+#' "meta refresh", which isn't the best way of doing a redirect but works 
+#' everywhere that you might deploy your site.
+#' 
+#' The syntax is the following, with old paths on the left, and new paths or 
+#' URLs on the right.
+#' 
+#' ```yaml
+#' redirects:
+#'   - ["articles/old-vignette-name.html", "articles/new-vignette-name.html"]
+#'   - ["articles/another-old-vignette-name.html", "articles/new-vignette-name.html"]
+#'   - ["articles/yet-another-old-vignette-name.html", "https://pkgdown.r-lib.org/dev"]
 #' ```
+#' 
+#' If for some reason you choose to redirect an existing page make sure to 
+#' exclude it from the search index, see `?build_search`.
 #'
 #' @section Options:
 #' Users with limited internet connectivity can disable CRAN checks by setting