[R-pkg-devel] How to build *-package description from *-package.R files ... and a luser/newbie question about pkgdown

[Duncan Murdoch]

On 12/02/2021 6:28 a.m., Chris Evans wrote:
> This feels embarrassingly trivial compared with most of the posts I try to understand here: apologies.
> 
> I am taking my first clumsy steps to build my own library of source code functions I have created and use a lot and want to share with a few collaborators.  I tried once before, a few years ago and failed to show the perseverance to succeed.  With help from so many wonderful tools so many people have created, and working in Rstudio, I do now have a package with some functions that work and a bit of function documentation.  It's at https://github.com/cpsyctc/CECPfuns if that helps anyone help me with my questions below ... if you do look you'll see it's just a baby steps as yet and there's a huge amount still to do.
> 
> Q1: I don't envisage it ever going beyond github but I would still like to document it well.  I am starting to understand documenting functions using the Code, Document in Rstudio and seem to have found good examples and documentation for that.  However, I am failing to find similar information about creating the CECPfuns-package documentation I would like to build.  I have a CECPfuns-package.R that I think I created with a packaged function that generates that skeleton (embarrassingly, I have forgotten now what that was).   I think that created my CECPfuns-package.Rd so I do have a vestigial answer to CECPfuns-package.  I also have a CECPfuns-package.Rd file generated with utils::promptPackage but I have left this in my package root directory (against the warning note) as it looks as if people recommend creating package documentation from *-package.R files in the R directory and I guess I'd prefer not to have to learn .Rd syntax if I can stick with working from R (or Rmd?).  I did c
>   reate a minimal one but CECPfuns.R (in the R directory) but I'm not sure what syntax I should be using to build on that.  So ...  I would really like to find advice on how to build CECPfuns-package docucmentation from that file or I'd love it if someone has created package documentation from a *-package.R file they'd be willing to share with me.

There are two general approaches for writing help pages in R.

The older approach (that I use) is to use functions like prompt() and 
promptPackage() to create skeletons of documentation in the man 
directory, then edit them by hand.  The main disadvantage of this 
approach is that the Rd format is pretty ugly:  it's kind of like LaTeX, 
but different enough that even if you know LaTeX, you'll have to spend 
some time learning it.  It's also a bit of a pain to keep your 
documentation in sync with your source code:  when you change the 
arguments to a function, you don't get automatic changes to the help page.

RStudio has pretty good support for this approach, in that you can 
preview the pages as you work on them, it knows a bit about their syntax 
so things are highlighted nicely, and there are easy methods to jump 
from a function to the corresponding .Rd file.

To set this up you uncheck the "Generate documentation with ROxygen" 
option in the project build tools options.  That's it!

The approach that a lot of newer packages use is to generate the .Rd 
files from comments in the .R files using Roxygen2.  In recent versions 
of Roxygen2, what you type can be entered in Markdown instead of Rd 
format.  Some parts of the Rd file will be generated automatically, so 
you don't need to type them at all:  that's another advantage.

What I don't like about this approach is:

  - Mixing source code and documentation makes your source files bigger 
which discourages careful documentation and makes it harder to read the 
code.  Source and docs are different things, so in my opinion, they 
shouldn't be mixed in the same file.

  - I don't think RStudio supports a "Preview" for the help page for a 
function (but I might be wrong about this, since I don't use it much).

On the other hand, it's definitely quicker to learn and to get minimal 
documentation out of the Roxygen approach.

In my opinion, what would be ideal is to have separate files for source 
and docs, with a less ugly format for the docs, and some kind of 
automatic link between source and doc files so updates to one are 
reflected in the other (or at least differences are signalled).


> Q2: I think I have realised that the html structure for packages that I'm so used to on CRAN isn't built by default when you build a package and I think the process may be automated by the pkgDown package and I've tried that putting the output (again, against the warning note) into tempDir below my package root.  Again, though the documentation for pkgDown seem clear on the functions it seems (to me) thin on exactly what is being done and how, assuming it's possible, to elaborate on the html that generates, I am failing to find more on those topics.
> Q2a: is there any danger of overwriting anything important in my minimal github repository were I to use pkgDown::build_site() to write directly to that repository?
> Q2b: is there more documentation on enhancing the site build_site() creates that I can read?
> 

I don't use pkgDown, so can't comment on these questions.

Duncan Murdoch