Change the order of fragments

[etiennebacher]

Hello, thank you for this package!

Is there a way to customize the order of the fragments in the output? In the example below, I'd like to put the description between the title and the usage:

  tmp <- tempfile(fileext = ".Rd")
  cat("
  % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/source.R
\\name{Foo}
\\title{Foo}
\\usage{
foo()
}
\\value{
Some value
}
\\description{
Some description
}
\\examples{
# some example
}
  ", file = tmp)
  
  cat(rd2markdown::rd2markdown(file = tmp))
#> 
#> 
#> # Foo
#> 
#> ```r
#> foo()
#> ```
#> 
#> ## Returns
#> 
#> Some value
#> 
#> Some description
#> 
#> ## Examples
#> 
#> ```r
#> # some example
#> ```

Using the argument fragments doesn't change anything:

  tmp <- tempfile(fileext = ".Rd")
  cat("
  % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/source.R
\\name{Foo}
\\title{Foo}
\\usage{
foo()
}
\\value{
Some value
}
\\description{
Some description
}
\\examples{
# some example
}
  ", file = tmp)
  
  cat(rd2markdown::rd2markdown(file = tmp, fragments = c("title", "description", "usage", "value", "examples")))
#> # Foo
#> 
#> ```r
#> foo()
#> ```
#> 
#> ## Returns
#> 
#> Some value
#> 
#> Some description
#> 
#> ## Examples
#> 
#> ```r
#> # some example
#> ```

Thanks

[dgkf-roche]

Hi there! This must have arrived at a hectic time because it slipped past us. It looks like your work in polars has pushed forward regardless, but I'll reply to have a position out there.

To keep the scope minimal, this is probably not a feature we will support within the rendering functionality.

That said, I would consider adding some processing utilities for manipulating Rd objects themselves. This would be more of a "power-user" API, composing a few of the components to allow for this capability. It could look something like this:

rd <- get_rd("<topic>", "<package>")
rd <- arrange_fragments(rd, ...)
md <- rd2markdown(rd)

Ideally this would be a capability that is readily available outside of this package so it is more easily repurposed for other render targets, but without a more generic solution out there it could potentially live in this package for now and would be deprecated if a more generic solution pops up elsewhere.

[etiennebacher]

Thanks for your answer @dgkf-roche. I have indeed moved forward and no longer have a clear use case for this, so feel free to close :)

[mannau]

@dgkf-roche this is also a feature we need through rd2markdown::documentation_to_markdown() and as a user it is not entirely clear (to me at least) why the order of the fragments vector parameter is not respected.

Could you give me a hint, how documentation_to_markdown() should be used in combination with an external arrange_fragments(rd, ...) function?