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

From: "Duncan Murdoch" <murdoch.duncan at gmail.com>
To: "Chris Evans" <chrishold at psyctc.org>, "r-package-devel" <r-package-devel at r-project.org>
Sent: Friday, 12 February, 2021 13:50:01
Subject: Re: [R-pkg-devel] How to build *-package description from *-package.R files ... and a luser/newbie question
about pkgdown

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