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

[Chris Evans]

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

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?

TIA and very best to all,

Chris

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