From c00e2e76b58c0056be8551b1e0e45f6362a04a27 Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 18 Nov 2021 11:00:57 +0100 Subject: [PATCH 1/3] add @noamross suggested modification to family tag text --- pkg_building.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 79f2b0921..262879a05 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -205,7 +205,7 @@ can be found at *link*". * All functions should document the type of object returned under the `@return` heading. -* We recommend using the `@family` tag in the documentation of functions to allow their grouping in the documentation of the installed package and potentially in the package's website, see [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. +- Documentation should support user navigation by including useful cross-links between related functions and documenting related functions together in groups or in common help pages. The @seealso and @family tags (the latter of which automatically creates “See also” links and groups functions together on pkgdown sites), are recommended for this purpose. See [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. * You could re-use documentation pieces (e.g. details about authentication, related packages) across the vignettes/README/man pages. A possible approach for that is the use of [R Markdown fragments, relying on knitr use of child documents so you can store the re-used parts in a folder in man/, and call them from both the README and the vignette](https://www.garrickadenbuie.com/blog/dry-vignette-and-readme/) as well [as in man pages by using the `@includeRmd` tag available from `roxygen 0.7.0`](https://roxygen2.r-lib.org/articles/rd.html#including-external--rmd-md-files). From 16a91cf865f43a6865efb3644059346e0794fbd7 Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 18 Nov 2021 15:00:15 +0100 Subject: [PATCH 2/3] thanks to @maelle for additional useful hyperlink --- pkg_building.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 262879a05..3caccec16 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -205,7 +205,7 @@ can be found at *link*". * All functions should document the type of object returned under the `@return` heading. -- Documentation should support user navigation by including useful cross-links between related functions and documenting related functions together in groups or in common help pages. The @seealso and @family tags (the latter of which automatically creates “See also” links and groups functions together on pkgdown sites), are recommended for this purpose. See [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. +- Documentation should support user navigation by including useful cross-links between related functions and documenting related functions together in groups or in common help pages. The @seealso and @family tags (the latter of which automatically creates “See also” links and [can help group](https://pkgdown.r-lib.org/reference/build_reference.html) functions together on pkgdown sites), are recommended for this purpose. See [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. * You could re-use documentation pieces (e.g. details about authentication, related packages) across the vignettes/README/man pages. A possible approach for that is the use of [R Markdown fragments, relying on knitr use of child documents so you can store the re-used parts in a folder in man/, and call them from both the README and the vignette](https://www.garrickadenbuie.com/blog/dry-vignette-and-readme/) as well [as in man pages by using the `@includeRmd` tag available from `roxygen 0.7.0`](https://roxygen2.r-lib.org/articles/rd.html#including-external--rmd-md-files). From 20e3bea63226437411a6fb148f485c5ea46cc1ad Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 18 Nov 2021 15:03:04 +0100 Subject: [PATCH 3/3] update changelog for #361 --- appendix.Rmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/appendix.Rmd b/appendix.Rmd index d6d2d6129..40f07cd47 100644 --- a/appendix.Rmd +++ b/appendix.Rmd @@ -4,6 +4,8 @@ ## dev +- 2021-11-18, update advice on grouping functions for pkgdown output (#361) + * 2021-11-04, add mentions of stat software review to software review intro and to the first book page (#342). * 2021-11-04, mention pkgcheck in the author guide (@mpadge, #343).