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

[Chris Evans]

Thanks Duncan,

Some comments and hopes for others to follow that lead inline below but great to take from this an overarching 
idea that I am not just being dumb.  More below ...

----- Original Message -----
> From: "Duncan Murdoch" <murdoch.duncan using gmail.com>
> To: "Chris Evans" <chrishold using psyctc.org>, "r-package-devel" <r-package-devel using 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.

Yes. I can see the arguments you make below about mixing source and 
documentation but I have found the Rstudio help with documenting 
functions at least a very good starting point.  It, i.e. Rstudio,
just doesn't seem to have created something for documentation of a
package.
 
> To set this up you uncheck the "Generate documentation with ROxygen"
> option in the project build tools options.  That's it!

Yup.  I like 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.

Again, yes, I have been following the "Rstudio wrapped" version of this
so far and again, can see your points but it feels a bit the mixing of
code and commentary feels familiar to me from mixing code blocks and 
text blocks in Rmarkdown (I can see it's not quite the same but I think
some years now using Rmarkdown made this easier to accept and start 
using).
> 
> 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).

I haven't found it if it is there.  I'm guessing you use ESS?

> 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).

Understood and all helpful and reassuring me that I may not have missed something
very obvious.  In some ways the funny thing about creating a xxxx-package.R file
to create the package document is a sort of edge case of what you're saying: it's 
creating a file that says it's a source code file when it won't actually contain
any source code at all!  However, I think that's what I see pointers suggesting
it's what I should do ... but not much on how.
> 
> 
>> 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.

Thanks though!!

Very best all,

Chris
> 
> Duncan Murdoch

-- 
Small contribution in our coronavirus rigours: 
https://www.coresystemtrust.org.uk/home/free-options-to-replace-paper-core-forms-during-the-coronavirus-pandemic/

Chris Evans <chris using psyctc.org> Visiting Professor, University of Sheffield <chris.evans using sheffield.ac.uk>
I do some consultation work for the University of Roehampton <chris.evans using roehampton.ac.uk> and other places
but <chris using psyctc.org> remains my main Email address.  I have a work web site at:
   https://www.psyctc.org/psyctc/
and a site I manage for CORE and CORE system trust at:
   http://www.coresystemtrust.org.uk/
I have "semigrated" to France, see: 
   https://www.psyctc.org/pelerinage2016/semigrating-to-france/ 
   https://www.psyctc.org/pelerinage2016/register-to-get-updates-from-pelerinage2016/

If you want an Emeeting, I am trying to keep them to Thursdays and my diary is at:
   https://www.psyctc.org/pelerinage2016/ceworkdiary/
Beware: French time, generally an hour ahead of UK.