From 6d264b5f16fbfd54c4c25a8eca6c81b1017e20e1 Mon Sep 17 00:00:00 2001 From: Etienne Bacher <52219252+etiennebacher@users.noreply.github.com> Date: Wed, 26 Feb 2025 23:07:44 +0100 Subject: [PATCH] Change CSS from `nowrap` to `collapse` in function arguments (#308) --- NEWS.md | 84 +++--- R/rd2qmd.R | 2 +- tests/testthat/_snaps/docsify/render_docs.md | 284 +++++++++---------- tests/testthat/_snaps/docute/render_docs.md | 284 +++++++++---------- tests/testthat/_snaps/mkdocs/render_docs.md | 128 ++++----- 5 files changed, 395 insertions(+), 387 deletions(-) diff --git a/NEWS.md b/NEWS.md index 30681e1..1dd755c 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,13 @@ # News +## development version + +### Changes + +* The CSS for arguments table in "Reference" page has changed a bit. Argument + names are now wrapped so that they have limited width, improving the + readibility in case of multiple arguments on the same line (#308). + ## 0.5.0 ### Breaking changes @@ -8,7 +16,7 @@ ### Other changes -* `README.qmd` is no longer required to create a `quarto_website`, only +* `README.qmd` is no longer required to create a `quarto_website`, only `README.md` (#295). ### Bug fixes @@ -31,7 +39,7 @@ ### New features * `render_docs(freeze = TRUE)` now works correctly when output is `"quarto_website"`. - Freezing a document needs to be set either at a project or per-file level. To do + Freezing a document needs to be set either at a project or per-file level. To do so, add to either `quarto_website.yml` or the frontmatter of a file: ``` yml @@ -39,7 +47,7 @@ freeze: auto ``` * For Quarto websites, `render_docs()` can use the `downlit` package to automatically - link function calls to their documentation on the web. Turn off by modifying + link function calls to their documentation on the web. Turn off by modifying the `code-link` line in `altdoc/quarto_website.yml` * Citation is now formatted with HTML instead of verbatim (#282, Achim Zeileis). * The `\doi{}` tags in Rd files are now linked once rendered (#282, Achim Zeileis). @@ -54,22 +62,22 @@ ## 0.3.0 -All functions have changed so any change listed below technically is a breaking +All functions have changed so any change listed below technically is a breaking change. ### Breaking changes * Functions renamed: - - `use_docute()`, `use_docsify()` and `use_mkdocs()` are combined into `setup_docs()` + - `use_docute()`, `use_docsify()` and `use_mkdocs()` are combined into `setup_docs()` - `update_docs()` -> `render_docs()` - `preview()` -> `preview_docs()` - -* `setup_docs()` (previously `use_*()`) no longer updates and previews the website + +* `setup_docs()` (previously `use_*()`) no longer updates and previews the website by default. -* `custom_reference` argument is removed. See the `Post-processing` vignette for +* `custom_reference` argument is removed. See the `Post-processing` vignette for a description of the new proposed workflow. -* `theme` argument is removed. Users can change themes by editing settings files +* `theme` argument is removed. Users can change themes by editing settings files in `altdoc/` * `mkdocs` documentation is no longer stored in `docs/docs/` @@ -79,30 +87,30 @@ change. * Support Quarto vignettes (.qmd) in the `vignettes/` folder. -* `render_docs(parallel = TRUE)` uses `future` to parallelize the rendering of +* `render_docs(parallel = TRUE)` uses `future` to parallelize the rendering of vignettes and man pages. - + * `render_docs(freeze = TRUE)` no longer renders vignettes or man pages when they have not changed and are already stored in `docs/`. - + * Link to source code at the top of function reference. -* Settings files are now permanently stored in the `altdoc/` directory. These +* Settings files are now permanently stored in the `altdoc/` directory. These files can be edited manually to customize the website. - -* Major internal changes to the .Rd -> .md conversion system. We now use Quarto - to convert man pages and execute examples, and the man pages are stored in + +* Major internal changes to the .Rd -> .md conversion system. We now use Quarto + to convert man pages and execute examples, and the man pages are stored in separate markdown files instead of combined in a single large file. - -* `mkdocs` now behaves like the other documentation generators and stores its - files in `docs/`. This means that `mkdocs` websites can be deployed to Github + +* `mkdocs` now behaves like the other documentation generators and stores its + files in `docs/`. This means that `mkdocs` websites can be deployed to Github Pages. - + * Improved vignettes -* Do not reformat markdown header levels automatically, but raise a warning when +* Do not reformat markdown header levels automatically, but raise a warning when there is more than one level 1 header. - + * Fewer dependencies. * Fix parsing for issue/PR references like [org/repo#111]. @@ -117,45 +125,45 @@ change. ## 0.2.2 -* If necessary, two spaces are automatically added in nested lists in the `NEWS` - (or `Changelog`) file. - +* If necessary, two spaces are automatically added in nested lists in the `NEWS` + (or `Changelog`) file. + * This is the last release before a large rework of this package. ## 0.2.1 -* Fix test failures on CRAN due to the new version of `usethis` +* Fix test failures on CRAN due to the new version of `usethis` (see https://github.com/cynkra/fledge/issues/683). -## 0.2.0 +## 0.2.0 #### Breaking changes * Vignettes are no longer automatically added to the file that defines the structure of the website. Developers must now manually update this structure and the order - of their articles. Note that the name of the file defining the structure of the + of their articles. Note that the name of the file defining the structure of the website differs based on the selected site builder. This file lives at the root - of `/docs` (`use_docsify()` = `_sidebar.md`; `use_docute()` = `index.html`; + of `/docs` (`use_docsify()` = `_sidebar.md`; `use_docute()` = `index.html`; `use_mkdocs()` = `mkdocs.yml`). - + #### Major changes - -* `update_docs()` now updates the package version as well as altdoc version in + +* `update_docs()` now updates the package version as well as altdoc version in the footer. - + * The NEWS or Changelog file included in the docs now automatically links issues, pull requests and users (only works for projects on Github). - + * Vignettes are now always rendered by `use_*()` or `update_docs()`. Therefore, - the argument `convert_vignettes` is removed. Previously, they were only rendered - if their content changed. This was problematic because the code in a vignette + the argument `convert_vignettes` is removed. Previously, they were only rendered + if their content changed. This was problematic because the code in a vignette can have different output while the vignette in itself doesn't change (#37, #38). - + * New argument `custom_reference` in `use_*()` and `update_docs()`. If it is a path to a custom R file then it uses this file to build the "Reference" section in the docs (#35). - + #### Minor changes * Fix some CRAN failures. diff --git a/R/rd2qmd.R b/R/rd2qmd.R index 495352c..b5489a4 100644 --- a/R/rd2qmd.R +++ b/R/rd2qmd.R @@ -21,7 +21,7 @@ idx <- idx[seq_along(idx) %% 2 == 1] tmp[idx] <- sub( "
hello_base(x = 2)"
- [12] "
"
- [13] ""
- [14] "## Arguments"
- [15] ""
- [16] ""
- [19] "x "
- [20] " | "
- [21] "" - [22] "A parameter" - [23] " | " - [24] "
pl$when(condition)
and"
- [30] "pl$then(output)
"
- [31] ""
- [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2"
- [33] ""
- [34] "## Value"
- [35] ""
- [36] "Some value"
- [37] ""
- [38] "## References"
- [39] ""
- [40] "Ihaka R, Gentleman R (1996). R: A Language for Data Analysis and"
- [41] "Graphics. Journal of Computational and Graphical Statistics."
- [42] "5(3), 299–314."
- [43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
- [44] ""
- [45] "## See Also"
- [46] ""
- [47] "print
, hello_r6
"
- [48] ""
- [49] "## Examples"
- [50] ""
- [51] "``` r"
- [52] "library(\"testpkg.altdoc\")"
- [53] ""
- [54] "hello_base()"
- [55] "```"
- [56] ""
- [57] " [1] \"Hello, world!\""
- [58] ""
- [59] "``` r"
- [60] "mtcars$drat <- mtcars$drat + 1"
- [61] "head(mtcars[[\"drat\"]], 2)"
- [62] "```"
- [63] ""
- [64] " [1] 4.9 4.9"
+ [1] ""
+ [2] ""
+ [3] "# Base function"
+ [4] ""
+ [5] "## Description"
+ [6] ""
+ [7] "Base function"
+ [8] ""
+ [9] "## Usage"
+ [10] ""
+ [11] "hello_base(x = 2)"
+ [12] "
"
+ [13] ""
+ [14] "## Arguments"
+ [15] ""
+ [16] ""
+ [19] "x "
+ [20] " | "
+ [21] "" + [22] "A parameter" + [23] " | " + [24] "
pl$when(condition)
and"
+ [30] "pl$then(output)
"
+ [31] ""
+ [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2"
+ [33] ""
+ [34] "## Value"
+ [35] ""
+ [36] "Some value"
+ [37] ""
+ [38] "## References"
+ [39] ""
+ [40] "Ihaka R, Gentleman R (1996). R: A Language for Data Analysis and"
+ [41] "Graphics. Journal of Computational and Graphical Statistics."
+ [42] "5(3), 299–314."
+ [43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
+ [44] ""
+ [45] "## See Also"
+ [46] ""
+ [47] "print
, hello_r6
"
+ [48] ""
+ [49] "## Examples"
+ [50] ""
+ [51] "``` r"
+ [52] "library(\"testpkg.altdoc\")"
+ [53] ""
+ [54] "hello_base()"
+ [55] "```"
+ [56] ""
+ [57] " [1] \"Hello, world!\""
+ [58] ""
+ [59] "``` r"
+ [60] "mtcars$drat <- mtcars$drat + 1"
+ [61] "head(mtcars[[\"drat\"]], 2)"
+ [62] "```"
+ [63] ""
+ [64] " [1] 4.9 4.9"
---
@@ -351,90 +351,90 @@
Code
.readlines("docs/man/examplesIf_true.md")
Output
- [1] ""
- [2] ""
- [3] "# Examples If TRUE"
- [4] ""
- [5] "## Description"
- [6] ""
- [7] "Examples If TRUE"
- [8] ""
- [9] "## Usage"
- [10] ""
- [11] "examplesIf_true()"
- [12] "
"
- [13] ""
- [14] "## Arguments"
- [15] ""
- [16] ""
- [19] "x "
- [20] " | "
- [21] "" - [22] "A parameter" - [23] " | " - [24] "
examplesIf_true()"
+ [12] "
"
+ [13] ""
+ [14] "## Arguments"
+ [15] ""
+ [16] ""
+ [19] "x "
+ [20] " | "
+ [21] "" + [22] "A parameter" + [23] " | " + [24] "
examplesIf_false()"
- [12] "
"
- [13] ""
- [14] "## Arguments"
- [15] ""
- [16] ""
- [19] "x "
- [20] " | "
- [21] "" - [22] "A parameter" - [23] " | " - [24] "
examplesIf_false()"
+ [12] "
"
+ [13] ""
+ [14] "## Arguments"
+ [15] ""
+ [16] ""
+ [19] "x "
+ [20] " | "
+ [21] "" + [22] "A parameter" + [23] " | " + [24] "
hello_base(x = 2)"
- [12] "
"
- [13] ""
- [14] "## Arguments"
- [15] ""
- [16] ""
- [19] "x "
- [20] " | "
- [21] "" - [22] "A parameter" - [23] " | " - [24] "
pl$when(condition)
and"
- [30] "pl$then(output)
"
- [31] ""
- [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2"
- [33] ""
- [34] "## Value"
- [35] ""
- [36] "Some value"
- [37] ""
- [38] "## References"
- [39] ""
- [40] "Ihaka R, Gentleman R (1996). R: A Language for Data Analysis and"
- [41] "Graphics. Journal of Computational and Graphical Statistics."
- [42] "5(3), 299–314."
- [43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
- [44] ""
- [45] "## See Also"
- [46] ""
- [47] "print
, hello_r6
"
- [48] ""
- [49] "## Examples"
- [50] ""
- [51] "``` r"
- [52] "library(\"testpkg.altdoc\")"
- [53] ""
- [54] "hello_base()"
- [55] "```"
- [56] ""
- [57] " [1] \"Hello, world!\""
- [58] ""
- [59] "``` r"
- [60] "mtcars$drat <- mtcars$drat + 1"
- [61] "head(mtcars[[\"drat\"]], 2)"
- [62] "```"
- [63] ""
- [64] " [1] 4.9 4.9"
+ [1] ""
+ [2] ""
+ [3] "# Base function"
+ [4] ""
+ [5] "## Description"
+ [6] ""
+ [7] "Base function"
+ [8] ""
+ [9] "## Usage"
+ [10] ""
+ [11] "hello_base(x = 2)"
+ [12] "
"
+ [13] ""
+ [14] "## Arguments"
+ [15] ""
+ [16] ""
+ [19] "x "
+ [20] " | "
+ [21] "" + [22] "A parameter" + [23] " | " + [24] "
pl$when(condition)
and"
+ [30] "pl$then(output)
"
+ [31] ""
+ [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2"
+ [33] ""
+ [34] "## Value"
+ [35] ""
+ [36] "Some value"
+ [37] ""
+ [38] "## References"
+ [39] ""
+ [40] "Ihaka R, Gentleman R (1996). R: A Language for Data Analysis and"
+ [41] "Graphics. Journal of Computational and Graphical Statistics."
+ [42] "5(3), 299–314."
+ [43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
+ [44] ""
+ [45] "## See Also"
+ [46] ""
+ [47] "print
, hello_r6
"
+ [48] ""
+ [49] "## Examples"
+ [50] ""
+ [51] "``` r"
+ [52] "library(\"testpkg.altdoc\")"
+ [53] ""
+ [54] "hello_base()"
+ [55] "```"
+ [56] ""
+ [57] " [1] \"Hello, world!\""
+ [58] ""
+ [59] "``` r"
+ [60] "mtcars$drat <- mtcars$drat + 1"
+ [61] "head(mtcars[[\"drat\"]], 2)"
+ [62] "```"
+ [63] ""
+ [64] " [1] 4.9 4.9"
---
@@ -342,90 +342,90 @@
Code
.readlines("docs/man/examplesIf_true.md")
Output
- [1] ""
- [2] ""
- [3] "# Examples If TRUE"
- [4] ""
- [5] "## Description"
- [6] ""
- [7] "Examples If TRUE"
- [8] ""
- [9] "## Usage"
- [10] ""
- [11] "examplesIf_true()"
- [12] "
"
- [13] ""
- [14] "## Arguments"
- [15] ""
- [16] ""
- [19] "x "
- [20] " | "
- [21] "" - [22] "A parameter" - [23] " | " - [24] "
examplesIf_true()"
+ [12] "
"
+ [13] ""
+ [14] "## Arguments"
+ [15] ""
+ [16] ""
+ [19] "x "
+ [20] " | "
+ [21] "" + [22] "A parameter" + [23] " | " + [24] "
examplesIf_false()"
- [12] "
"
- [13] ""
- [14] "## Arguments"
- [15] ""
- [16] ""
- [19] "x "
- [20] " | "
- [21] "" - [22] "A parameter" - [23] " | " - [24] "
examplesIf_false()"
+ [12] "
"
+ [13] ""
+ [14] "## Arguments"
+ [15] ""
+ [16] ""
+ [19] "x "
+ [20] " | "
+ [21] "" + [22] "A parameter" + [23] " | " + [24] "
hello_base(x = 2)"
- [12] "
"
- [13] ""
- [14] "## Arguments"
- [15] ""
- [16] ""
- [19] "x "
- [20] " | "
- [21] "" - [22] "A parameter" - [23] " | " - [24] "
pl$when(condition)
and"
- [30] "pl$then(output)
"
- [31] ""
- [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2"
- [33] ""
- [34] "## Value"
- [35] ""
- [36] "Some value"
- [37] ""
- [38] "## References"
- [39] ""
- [40] "Ihaka R, Gentleman R (1996). R: A Language for Data Analysis and"
- [41] "Graphics. Journal of Computational and Graphical Statistics."
- [42] "5(3), 299–314."
- [43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
- [44] ""
- [45] "## See Also"
- [46] ""
- [47] "print
, hello_r6
"
- [48] ""
- [49] "## Examples"
- [50] ""
- [51] "``` r"
- [52] "library(\"testpkg.altdoc\")"
- [53] ""
- [54] "hello_base()"
- [55] "```"
- [56] ""
- [57] " [1] \"Hello, world!\""
- [58] ""
- [59] "``` r"
- [60] "mtcars$drat <- mtcars$drat + 1"
- [61] "head(mtcars[[\"drat\"]], 2)"
- [62] "```"
- [63] ""
- [64] " [1] 4.9 4.9"
+ [1] ""
+ [2] ""
+ [3] "# Base function"
+ [4] ""
+ [5] "## Description"
+ [6] ""
+ [7] "Base function"
+ [8] ""
+ [9] "## Usage"
+ [10] ""
+ [11] "hello_base(x = 2)"
+ [12] "
"
+ [13] ""
+ [14] "## Arguments"
+ [15] ""
+ [16] ""
+ [19] "x "
+ [20] " | "
+ [21] "" + [22] "A parameter" + [23] " | " + [24] "
pl$when(condition)
and"
+ [30] "pl$then(output)
"
+ [31] ""
+ [32] "Some equations: ∂*Y*/∂*X* = *a* + *ε*/2"
+ [33] ""
+ [34] "## Value"
+ [35] ""
+ [36] "Some value"
+ [37] ""
+ [38] "## References"
+ [39] ""
+ [40] "Ihaka R, Gentleman R (1996). R: A Language for Data Analysis and"
+ [41] "Graphics. Journal of Computational and Graphical Statistics."
+ [42] "5(3), 299–314."
+ [43] "[doi:10.2307/139080](https://doi.org/10.2307/139080)"
+ [44] ""
+ [45] "## See Also"
+ [46] ""
+ [47] "print
, hello_r6
"
+ [48] ""
+ [49] "## Examples"
+ [50] ""
+ [51] "``` r"
+ [52] "library(\"testpkg.altdoc\")"
+ [53] ""
+ [54] "hello_base()"
+ [55] "```"
+ [56] ""
+ [57] " [1] \"Hello, world!\""
+ [58] ""
+ [59] "``` r"
+ [60] "mtcars$drat <- mtcars$drat + 1"
+ [61] "head(mtcars[[\"drat\"]], 2)"
+ [62] "```"
+ [63] ""
+ [64] " [1] 4.9 4.9"
---