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( "", - '', + '', tmp[idx] ) diff --git a/tests/testthat/_snaps/docsify/render_docs.md b/tests/testthat/_snaps/docsify/render_docs.md index 817e3ea..c265cc3 100644 --- a/tests/testthat/_snaps/docsify/render_docs.md +++ b/tests/testthat/_snaps/docsify/render_docs.md @@ -127,70 +127,70 @@ Code .readlines("docs/man/hello_base.md") Output - [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] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Details" - [28] "" - [29] "Some code with weird symbols: 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] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Details" + [28] "" + [29] "Some code with weird symbols: 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] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Value" - [28] "" - [29] "Some value" - [30] "" - [31] "## Examples" - [32] "" - [33] "``` r" - [34] "library(\"testpkg.altdoc\")" - [35] "" - [36] "" - [37] "examplesIf_true()" - [38] "```" - [39] "" - [40] " [1] \"Hello, world!\"" + [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] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Value" + [28] "" + [29] "Some value" + [30] "" + [31] "## Examples" + [32] "" + [33] "``` r" + [34] "library(\"testpkg.altdoc\")" + [35] "" + [36] "" + [37] "examplesIf_true()" + [38] "```" + [39] "" + [40] " [1] \"Hello, world!\"" --- Code .readlines("docs/man/examplesIf_false.md") Output - [1] "" - [2] "" - [3] "# Examples If FALSE" - [4] "" - [5] "## Description" - [6] "" - [7] "Examples If FALSE" - [8] "" - [9] "## Usage" - [10] "" - [11] "
examplesIf_false()"                               
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Value" - [28] "" - [29] "Some value" - [30] "" - [31] "## Examples" - [32] "" - [33] "``` r" - [34] "library(\"testpkg.altdoc\")" - [35] "" - [36] "" - [37] "examplesIf_false()" - [38] "```" + [1] "" + [2] "" + [3] "# Examples If FALSE" + [4] "" + [5] "## Description" + [6] "" + [7] "Examples If FALSE" + [8] "" + [9] "## Usage" + [10] "" + [11] "
examplesIf_false()"                                 
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Value" + [28] "" + [29] "Some value" + [30] "" + [31] "## Examples" + [32] "" + [33] "``` r" + [34] "library(\"testpkg.altdoc\")" + [35] "" + [36] "" + [37] "examplesIf_false()" + [38] "```" --- diff --git a/tests/testthat/_snaps/docute/render_docs.md b/tests/testthat/_snaps/docute/render_docs.md index 1464fd5..2451e9d 100644 --- a/tests/testthat/_snaps/docute/render_docs.md +++ b/tests/testthat/_snaps/docute/render_docs.md @@ -118,70 +118,70 @@ Code .readlines("docs/man/hello_base.md") Output - [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] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Details" - [28] "" - [29] "Some code with weird symbols: 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] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Details" + [28] "" + [29] "Some code with weird symbols: 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] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Value" - [28] "" - [29] "Some value" - [30] "" - [31] "## Examples" - [32] "" - [33] "``` r" - [34] "library(\"testpkg.altdoc\")" - [35] "" - [36] "" - [37] "examplesIf_true()" - [38] "```" - [39] "" - [40] " [1] \"Hello, world!\"" + [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] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Value" + [28] "" + [29] "Some value" + [30] "" + [31] "## Examples" + [32] "" + [33] "``` r" + [34] "library(\"testpkg.altdoc\")" + [35] "" + [36] "" + [37] "examplesIf_true()" + [38] "```" + [39] "" + [40] " [1] \"Hello, world!\"" --- Code .readlines("docs/man/examplesIf_false.md") Output - [1] "" - [2] "" - [3] "# Examples If FALSE" - [4] "" - [5] "## Description" - [6] "" - [7] "Examples If FALSE" - [8] "" - [9] "## Usage" - [10] "" - [11] "
examplesIf_false()"                               
-      [12] "
" - [13] "" - [14] "## Arguments" - [15] "" - [16] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Value" - [28] "" - [29] "Some value" - [30] "" - [31] "## Examples" - [32] "" - [33] "``` r" - [34] "library(\"testpkg.altdoc\")" - [35] "" - [36] "" - [37] "examplesIf_false()" - [38] "```" + [1] "" + [2] "" + [3] "# Examples If FALSE" + [4] "" + [5] "## Description" + [6] "" + [7] "Examples If FALSE" + [8] "" + [9] "## Usage" + [10] "" + [11] "
examplesIf_false()"                                 
+      [12] "
" + [13] "" + [14] "## Arguments" + [15] "" + [16] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Value" + [28] "" + [29] "Some value" + [30] "" + [31] "## Examples" + [32] "" + [33] "``` r" + [34] "library(\"testpkg.altdoc\")" + [35] "" + [36] "" + [37] "examplesIf_false()" + [38] "```" --- diff --git a/tests/testthat/_snaps/mkdocs/render_docs.md b/tests/testthat/_snaps/mkdocs/render_docs.md index 09a527c..aeecbc4 100644 --- a/tests/testthat/_snaps/mkdocs/render_docs.md +++ b/tests/testthat/_snaps/mkdocs/render_docs.md @@ -18,70 +18,70 @@ Code .readlines("docs/man/hello_base.md") Output - [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] "" - [17] "" - [18] "" - [21] "" - [24] "" - [25] "
" - [19] "x" - [20] "" - [22] "A parameter" - [23] "
" - [26] "" - [27] "## Details" - [28] "" - [29] "Some code with weird symbols: 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] "" + [17] "" + [18] "" + [21] "" + [24] "" + [25] "
" + [19] "x" + [20] "" + [22] "A parameter" + [23] "
" + [26] "" + [27] "## Details" + [28] "" + [29] "Some code with weird symbols: 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" ---