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.dun...@gmail.com> > To: "Chris Evans" <chrish...@psyctc.org>, "r-package-devel" > <r-package-devel@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 <ch...@psyctc.org> Visiting Professor, University of Sheffield <chris.ev...@sheffield.ac.uk> I do some consultation work for the University of Roehampton <chris.ev...@roehampton.ac.uk> and other places but <ch...@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. ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
