From f6d905cbb16b39863e0d0f918caa1316a9a20729 Mon Sep 17 00:00:00 2001
From: Hadley Wickham <h.wickham@gmail.com>
Date: Tue, 23 Apr 2024 16:53:13 -0500
Subject: [PATCH] Improve reference headings (#2491)

* Use markdown headings instead of roxygen2 tags
* Tweak heading hierarchy
---
 R/build-articles.R     | 16 ++++++++--------
 R/build-home.R         | 16 ++++++----------
 R/build-news.R         |  2 +-
 R/build-reference.R    |  6 +++---
 R/build-search-docs.R  |  4 ++--
 R/build-tutorials.R    |  2 +-
 R/build.R              | 20 +++++++++++---------
 R/init.R               |  2 +-
 man/build_articles.Rd  |  8 --------
 man/build_home.Rd      | 16 ++++++----------
 man/build_news.Rd      |  2 --
 man/build_reference.Rd |  8 ++------
 man/build_search.Rd    |  3 ---
 man/build_site.Rd      | 15 +++++----------
 man/build_tutorials.Rd |  1 -
 man/init_site.Rd       |  1 -
 16 files changed, 46 insertions(+), 76 deletions(-)

diff --git a/R/build-articles.R b/R/build-articles.R
index ddeb27406f..8ea5df88e2 100644
--- a/R/build-articles.R
+++ b/R/build-articles.R
@@ -19,7 +19,7 @@
 #' package, not the current source version. This makes iteration quicker when
 #' you are primarily working on the text of an article.
 #'
-#' @section Index and navbar:
+#' # Index and navbar
 #' You can control the articles index and navbar with a `articles` field in
 #' your `_pkgdown.yml`. If you use it, pkgdown will check that all articles
 #' are included, and will error if you have missed any.
@@ -77,7 +77,7 @@
 #' the navbar, it will link directly to the articles index instead of
 #' providing a drop-down.
 #'
-#' @section Get started:
+#' # Get started
 #' Note that a vignette with the same name as the package (e.g.,
 #' `vignettes/pkgdown.Rmd` or `vignettes/articles/pkgdown.Rmd`) automatically
 #' becomes a top-level "Get started" link, and will not appear in the articles
@@ -86,7 +86,7 @@
 #' (If your package name includes a `.`, e.g. `pack.down`, use a `-` in the
 #' vignette name, e.g. `pack-down.Rmd`.)
 #'
-#' @section External files:
+#' # External files
 #' pkgdown differs from base R in its handling of external files. When building
 #' vignettes, R assumes that vignettes are self-contained (a reasonable
 #' assumption when most vignettes were PDFs) and only copies files explicitly
@@ -107,7 +107,7 @@
 #' Note that you can not use the `fig.path` to change the output directory of
 #' generated figures as its default value is a strong assumption of rmarkdown.
 #'
-#' @section Embedding Shiny apps:
+#' # Embedding Shiny apps
 #' If you would like to embed a Shiny app into an article, the app will have
 #' to be hosted independently, (e.g. <https://www.shinyapps.io>). Then, you
 #' can embed the app into your article using an `<iframe>`, e.g.
@@ -116,7 +116,7 @@
 #' See <https://github.com/r-lib/pkgdown/issues/838#issuecomment-430473856> for
 #' some hints on how to customise the appearance with CSS.
 #'
-#' @section Output formats:
+#' # Output formats
 #' By default, pkgdown builds all articles using the
 #' [rmarkdown::html_document()] `output` format, ignoring whatever is set in
 #' your YAML metadata. This is necessary because pkgdown has to integrate the
@@ -148,15 +148,15 @@
 #'
 #' Additionally, htmlwidgets do not work when `as_is: true`.
 #'
-#' @inheritSection build_reference Figures
-#'
-#' @section Suppressing vignettes:
+#' # Suppressing vignettes
 #' If you want articles that are not vignettes, either put them in
 #' subdirectories or list in `.Rbuildignore`. An articles link will be
 #' automatically added to the default navbar if the vignettes directory is
 #' present: if you do not want this, you will need to customise the navbar. See
 #' [build_site()] details.
 #'
+#' @inheritSection build_reference Figures
+#'
 #' @inheritParams as_pkgdown
 #' @param quiet Set to `FALSE` to display output of knitr and
 #'   pandoc. This is useful when debugging.
diff --git a/R/build-home.R b/R/build-home.R
index ad10e8b720..8c085e59c5 100644
--- a/R/build-home.R
+++ b/R/build-home.R
@@ -68,12 +68,7 @@
 #' 
 #' [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
+#' ## YAML config - title and description
 #' 
 #' By default, the page title and description are extracted automatically from
 #' the `Title` and `Description` fields `DESCRIPTION` (stripping single quotes
@@ -91,7 +86,8 @@
 #'     to your growing collection.
 #' ```
 #' 
-#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.)
+#' (Note the use of YAML's `>` i.e. "YAML pipes"; this is a convenient way of 
+#' writing paragraphs of text.)
 #' 
 #' ## Dev badges
 #' 
@@ -154,9 +150,10 @@
 #'   )
 #' ```
 #' 
-#' ## YAML config - authors
+#' ## Additional control via YAML
 #' 
-#' You can tweak a few things via the `authors` YAML field:
+#' You can control additinal aspects of the authors display 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,
@@ -164,7 +161,6 @@
 #' * 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:
diff --git a/R/build-news.R b/R/build-news.R
index 23dbb0d73a..54703c3306 100644
--- a/R/build-news.R
+++ b/R/build-news.R
@@ -38,7 +38,7 @@
 #' be added to the heading (see below for how to suppress); if not
 #' available on CRAN, "Unreleased" will be added.
 #'
-#' @section YAML config:
+#' # YAML config
 #'
 #' To automatically link to release announcements, include a `releases`
 #' section.
diff --git a/R/build-reference.R b/R/build-reference.R
index b0c33c4158..4d8c3cc860 100644
--- a/R/build-reference.R
+++ b/R/build-reference.R
@@ -4,7 +4,7 @@
 #' alphabetical order. To override this, provide a `reference` section in your
 #' `_pkgdown.yml` as described below.
 #'
-#' @section Reference index:
+#' # Reference index
 #' To tweak the index page, add a section called `reference` to `_pkgdown.yml`.
 #' It can contain three different types of element:
 #'
@@ -104,12 +104,12 @@
 #' either 30x30 (for regular display) or 60x60 (if you want retina display).
 #' Icons are matched to topics by aliases.
 #'
-#' ## Examples
+#' # Examples
 #'
 #' If you need to run extra code before or after all examples are run, you
 #' can create `pkgdown/pre-reference.R` and `pkgdown/post-reference.R`.
 #'
-#' @section Figures:
+#' # Figures
 #'
 #' You can control the default rendering of figures by specifying the `figures`
 #' field in `_pkgdown.yml`. The default settings are equivalent to:
diff --git a/R/build-search-docs.R b/R/build-search-docs.R
index 012b939868..26cb18e193 100644
--- a/R/build-search-docs.R
+++ b/R/build-search-docs.R
@@ -62,7 +62,7 @@ url_node <- function(url) {
 #'
 #' Build a JSON file encompassing all HTML pages, for use by the search script.
 #'
-#' @section YAML config:
+#' # YAML config
 #' You can exclude some paths from the search index.
 #' Below we exclude the changelog from the search index.
 #'
@@ -70,7 +70,7 @@ url_node <- function(url) {
 #' search:
 #'   exclude: ['news/index.html']
 #' ```
-#' @section Debugging and local testing:
+#' # Debugging and local testing
 #'
 #' Locally (as opposed to on GitHub Pages or Netlify for instance),
 #' search won't work if you simply use pkgdown preview of the static files.
diff --git a/R/build-tutorials.R b/R/build-tutorials.R
index e75728fa77..b92357c51b 100644
--- a/R/build-tutorials.R
+++ b/R/build-tutorials.R
@@ -7,7 +7,7 @@
 #' `inst/tutorials` and `vignettes/tutorials`. Alternatively, you can
 #' list in `_pkgdown.yml` as described below.
 #'
-#' @section YAML config:
+#' # YAML config
 #' To override the default discovery process, you can provide a `tutorials`
 #' section. This should be a list where each element specifies:
 #'
diff --git a/R/build.R b/R/build.R
index 470abe7ed5..97ea45a3ae 100644
--- a/R/build.R
+++ b/R/build.R
@@ -44,7 +44,7 @@
 #' The `search` field controls the built-in search and is
 #' documented in `vignette("search")`.
 #'
-#' @section Development mode:
+#' # 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
 #' need to set the development `mode`:
@@ -133,11 +133,13 @@
 #' to danger). Finally, you can choose to override the default tooltip with
 #' `version_tooltip`.
 #'
-#' @section Template:
+#' # Template
 #' The `template` field is mostly used to control the appearance of the site.
-#' See `vignette("customise")` for details.
+#' See `vignette("customise")` for details. But it's also used to control
 #'
-#' There are two other `template` fields that control other aspects of the
+#' ## Other aspects
+#'
+#' There are a few other `template` fields that control other aspects of the
 #' site:
 #'
 #' *   `noindex: true` will suppress indexing of your pages by search engines:
@@ -166,7 +168,7 @@
 #'        trailing_slash_redirect: true
 #'      ```
 #'
-#' @section Analytics:
+#' ## Analytics
 #'
 #' To capture usage of your site with a web analytics tool, you can make
 #' use of the `includes` field to add the special HTML they need. This HTML
@@ -212,8 +214,8 @@
 #'           <script data-goatcounter="https://{YOUR CODE}.goatcounter.com/count" data-goatcounter-settings="{YOUR SETTINGS}" async src="https://gc.zgo.at/count.js"></script>
 #'     ```
 #'
+#' # Source repository
 #'
-#' @section Source repository:
 #' Use the `repo` field to override pkgdown's automatically discovery
 #' of your source repository. This is used in the navbar, on the homepage,
 #' in articles and reference topics, and in the changelog (to link to issue
@@ -260,7 +262,7 @@
 #'   branch: devel
 #' ```
 #'
-#' @section Deployment (`deploy`):
+#' # Deployment (`deploy`)
 #' There is a single `deploy` field
 #'
 #' *  `install_metadata` allows you to install package index metadata into
@@ -274,7 +276,7 @@
 #'      install_metadata: true
 #'    ```
 #'
-#' @section Redirects:
+#' # Redirects
 #' 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 
@@ -295,7 +297,7 @@
 #' 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:
+#' # Options
 #' Users with limited internet connectivity can disable CRAN checks by setting
 #' `options(pkgdown.internet = FALSE)`. This will also disable some features
 #' from pkgdown that requires an internet connectivity. However, if it is used
diff --git a/R/init.R b/R/init.R
index a594c118d5..31d2c9a413 100644
--- a/R/init.R
+++ b/R/init.R
@@ -11,7 +11,7 @@
 #' See `vignette("customise")` for the various ways you can customise the
 #' display of your site.
 #'
-#' @section Build-ignored files:
+#' # Build-ignored files
 #' We recommend using [usethis::use_pkgdown()] to build-ignore `docs/` and
 #' `_pkgdown.yml`. If use another directory, or create the site manually,
 #' you'll need to add them to `.Rbuildignore` yourself. A `NOTE` about
diff --git a/man/build_articles.Rd b/man/build_articles.Rd
index 756eec8a8f..0353cc0b1b 100644
--- a/man/build_articles.Rd
+++ b/man/build_articles.Rd
@@ -74,7 +74,6 @@ package, not the current source version. This makes iteration quicker when
 you are primarily working on the text of an article.
 }
 \section{Index and navbar}{
-
 You can control the articles index and navbar with a \code{articles} field in
 your \verb{_pkgdown.yml}. If you use it, pkgdown will check that all articles
 are included, and will error if you have missed any.
@@ -131,7 +130,6 @@ providing a drop-down.
 }
 
 \section{Get started}{
-
 Note that a vignette with the same name as the package (e.g.,
 \code{vignettes/pkgdown.Rmd} or \code{vignettes/articles/pkgdown.Rmd}) automatically
 becomes a top-level "Get started" link, and will not appear in the articles
@@ -142,7 +140,6 @@ vignette name, e.g. \code{pack-down.Rmd}.)
 }
 
 \section{External files}{
-
 pkgdown differs from base R in its handling of external files. When building
 vignettes, R assumes that vignettes are self-contained (a reasonable
 assumption when most vignettes were PDFs) and only copies files explicitly
@@ -164,7 +161,6 @@ generated figures as its default value is a strong assumption of rmarkdown.
 }
 
 \section{Embedding Shiny apps}{
-
 If you would like to embed a Shiny app into an article, the app will have
 to be hosted independently, (e.g. \url{https://www.shinyapps.io}). Then, you
 can embed the app into your article using an \verb{<iframe>}, e.g.
@@ -175,7 +171,6 @@ some hints on how to customise the appearance with CSS.
 }
 
 \section{Output formats}{
-
 By default, pkgdown builds all articles using the
 \code{\link[rmarkdown:html_document]{rmarkdown::html_document()}} \code{output} format, ignoring whatever is set in
 your YAML metadata. This is necessary because pkgdown has to integrate the
@@ -207,7 +202,6 @@ Additionally, htmlwidgets do not work when \code{as_is: true}.
 }
 
 \section{Suppressing vignettes}{
-
 If you want articles that are not vignettes, either put them in
 subdirectories or list in \code{.Rbuildignore}. An articles link will be
 automatically added to the default navbar if the vignettes directory is
@@ -216,8 +210,6 @@ present: if you do not want this, you will need to customise the navbar. See
 }
 
 \section{Figures}{
-
-
 You can control the default rendering of figures by specifying the \code{figures}
 field in \verb{_pkgdown.yml}. The default settings are equivalent to:
 
diff --git a/man/build_home.Rd b/man/build_home.Rd
index 6c5224112e..a06f06596f 100644
--- a/man/build_home.Rd
+++ b/man/build_home.Rd
@@ -87,11 +87,7 @@ in a level-one heading:
 \code{\link[=init_site]{init_site()}} will also automatically create a favicon set from your package logo.
 }
 
-\subsection{YAML config - home}{
-
-To tweak the home page, you need a section of the configuration file called
-\code{home}.
-\subsection{Page title and description}{
+\subsection{YAML config - title and description}{
 
 By default, the page title and description are extracted automatically from
 the \code{Title} and \code{Description} fields \code{DESCRIPTION} (stripping single quotes
@@ -108,9 +104,8 @@ findable on search engines, it's good practice to override the \code{title} and
     to your growing collection.
 }\if{html}{\out{</div>}}
 
-(Note the use of YAML's \code{>} i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.)
-}
-
+(Note the use of YAML's \code{>} i.e. "YAML pipes"; this is a convenient way of
+writing paragraphs of text.)
 }
 
 \subsection{Dev badges}{
@@ -173,9 +168,10 @@ authors page.
 }\if{html}{\out{</div>}}
 }
 
-\subsection{YAML config - authors}{
+\subsection{Additional control via YAML}{
 
-You can tweak a few things via the \code{authors} YAML field:
+You can control additinal aspects of the authors display via the \code{authors}
+YAML field:
 \itemize{
 \item display of each author in the footer, sidebar and authors page,
 \item which authors (by role) are displayed in the sidebar and footer,
diff --git a/man/build_news.Rd b/man/build_news.Rd
index 60515ce2e6..4da4a31965 100644
--- a/man/build_news.Rd
+++ b/man/build_news.Rd
@@ -54,8 +54,6 @@ be added to the heading (see below for how to suppress); if not
 available on CRAN, "Unreleased" will be added.
 }
 \section{YAML config}{
-
-
 To automatically link to release announcements, include a \code{releases}
 section.
 
diff --git a/man/build_reference.Rd b/man/build_reference.Rd
index 2c0f253960..ea29581874 100644
--- a/man/build_reference.Rd
+++ b/man/build_reference.Rd
@@ -56,7 +56,6 @@ alphabetical order. To override this, provide a \code{reference} section in your
 \verb{_pkgdown.yml} as described below.
 }
 \section{Reference index}{
-
 To tweak the index page, add a section called \code{reference} to \verb{_pkgdown.yml}.
 It can contain three different types of element:
 \itemize{
@@ -158,17 +157,14 @@ a top-level \code{icons} directory. This should contain {.png} files that are
 either 30x30 (for regular display) or 60x60 (if you want retina display).
 Icons are matched to topics by aliases.
 }
+}
 
-\subsection{Examples}{
-
+\section{Examples}{
 If you need to run extra code before or after all examples are run, you
 can create \code{pkgdown/pre-reference.R} and \code{pkgdown/post-reference.R}.
 }
-}
 
 \section{Figures}{
-
-
 You can control the default rendering of figures by specifying the \code{figures}
 field in \verb{_pkgdown.yml}. The default settings are equivalent to:
 
diff --git a/man/build_search.Rd b/man/build_search.Rd
index babca8d912..4d2fc04fea 100644
--- a/man/build_search.Rd
+++ b/man/build_search.Rd
@@ -16,7 +16,6 @@ values in \verb{_pkgdown.yml}}
 Build a JSON file encompassing all HTML pages, for use by the search script.
 }
 \section{YAML config}{
-
 You can exclude some paths from the search index.
 Below we exclude the changelog from the search index.
 
@@ -26,8 +25,6 @@ Below we exclude the changelog from the search index.
 }
 
 \section{Debugging and local testing}{
-
-
 Locally (as opposed to on GitHub Pages or Netlify for instance),
 search won't work if you simply use pkgdown preview of the static files.
 You can use \code{servr::httw("docs")} instead.
diff --git a/man/build_site.Rd b/man/build_site.Rd
index 4d104d0c00..24b9bd1702 100644
--- a/man/build_site.Rd
+++ b/man/build_site.Rd
@@ -106,7 +106,6 @@ documented in \code{vignette("search")}.
 }
 
 \section{Development mode}{
-
 The \code{development} field allows you to generate different sites for the
 development and released versions of your package. To use it, you first
 need to set the development \code{mode}:
@@ -194,11 +193,11 @@ to danger). Finally, you can choose to override the default tooltip with
 }
 
 \section{Template}{
-
 The \code{template} field is mostly used to control the appearance of the site.
-See \code{vignette("customise")} for details.
+See \code{vignette("customise")} for details. But it's also used to control
+\subsection{Other aspects}{
 
-There are two other \code{template} fields that control other aspects of the
+There are a few other \code{template} fields that control other aspects of the
 site:
 \itemize{
 \item \code{noindex: true} will suppress indexing of your pages by search engines:
@@ -224,8 +223,7 @@ redirect scenarios.
 }
 }
 
-\section{Analytics}{
-
+\subsection{Analytics}{
 
 To capture usage of your site with a web analytics tool, you can make
 use of the \code{includes} field to add the special HTML they need. This HTML
@@ -268,9 +266,9 @@ recommend getting the HTML directly from the tool:
 }\if{html}{\out{</div>}}
 }
 }
+}
 
 \section{Source repository}{
-
 Use the \code{repo} field to override pkgdown's automatically discovery
 of your source repository. This is used in the navbar, on the homepage,
 in articles and reference topics, and in the changelog (to link to issue
@@ -317,7 +315,6 @@ specifying a branch name:
 }
 
 \section{Deployment (\code{deploy})}{
-
 There is a single \code{deploy} field
 \itemize{
 \item \code{install_metadata} allows you to install package index metadata into
@@ -333,7 +330,6 @@ time (e.g. because behind a firewall or requires auth).
 }
 
 \section{Redirects}{
-
 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
@@ -355,7 +351,6 @@ exclude it from the search index, see \code{?build_search}.
 }
 
 \section{Options}{
-
 Users with limited internet connectivity can disable CRAN checks by setting
 \code{options(pkgdown.internet = FALSE)}. This will also disable some features
 from pkgdown that requires an internet connectivity. However, if it is used
diff --git a/man/build_tutorials.Rd b/man/build_tutorials.Rd
index 5046f902b7..1d7abe9236 100644
--- a/man/build_tutorials.Rd
+++ b/man/build_tutorials.Rd
@@ -24,7 +24,6 @@ Tutorials are automatically discovered from published tutorials in
 list in \verb{_pkgdown.yml} as described below.
 }
 \section{YAML config}{
-
 To override the default discovery process, you can provide a \code{tutorials}
 section. This should be a list where each element specifies:
 \itemize{
diff --git a/man/init_site.Rd b/man/init_site.Rd
index 4046c15006..7d638ddf62 100644
--- a/man/init_site.Rd
+++ b/man/init_site.Rd
@@ -22,7 +22,6 @@ See \code{vignette("customise")} for the various ways you can customise the
 display of your site.
 }
 \section{Build-ignored files}{
-
 We recommend using \code{\link[usethis:use_pkgdown]{usethis::use_pkgdown()}} to build-ignore \verb{docs/} and
 \verb{_pkgdown.yml}. If use another directory, or create the site manually,
 you'll need to add them to \code{.Rbuildignore} yourself. A \code{NOTE} about