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
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
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 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.
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.
Apologies, I think that was clear.
Do you or anyone else have an example of a ****-package.R that Rstudio's check has built into a package documentation file that was well populated and useful?
I think that's the key exemplar I am seeking and I'm finding it hard to craft any web search that finds me such a thing.
Any offer?! TIA,
Chris
----- Original Message -----
From: "Duncan Murdoch" <murdoch.duncan at gmail.com>
To: "Chris Evans" <chrishold at psyctc.org>
Cc: "r-package-devel" <r-package-devel at r-project.org>
Sent: Friday, 12 February, 2021 15:40:25
Subject: Re: [R-pkg-devel] How to build *-package description from *-package.R files ... and a luser/newbie question
about pkgdown
Just one clarification:
On 12/02/2021 9:59 a.m., Chris Evans wrote:
[ lots deleted ]
- 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?
No, I use RStudio. When I said "I don't use it much", I meant Roxygen2.
Duncan Murdoch
Chris,
I have migrated from Travis CI to using GitHub actions with pkgdown to build websites for packages - see https://ropenscilabs.github.io/actions_sandbox/websites-using-pkgdown-bookdown-and-blogdown.html to set up. The GitHub action doesn?t use Rstudio?s check but does automatically update the documentation when the master branch is pushed to GitHub.
An example is at https://merliseclyde.github.io/BAS/index.html. (package is at https://github.com/merliseclyde/BAS ). One that is a work in progress is https://merliseclyde.github.io/bark - which was built from the start using the approach documented above - there is less customization there.
I do use pkgdown::build_site() in RStudio to preview the package documentation locally as well.
For documentation I did migrate to using roxygen2 several years ago from writing my own Rd files. I like the checks that it keeps the documentation in sync with changes in the function. The R Packages book by Hadley Wickham and Jennifer Bryan has a nice chapter on this https://r-pkgs.org/man.html
HTH,
Merlise
On Feb 12, 2021, at 10:52 AM, Chris Evans <chrishold at psyctc.org<mailto:chrishold at psyctc.org>> wrote:
Apologies, I think that was clear.
Do you or anyone else have an example of a ****-package.R that Rstudio's check has built into a package documentation file that was well populated and useful?
I think that's the key exemplar I am seeking and I'm finding it hard to craft any web search that finds me such a thing.
Any offer?! TIA,
Chris
----- Original Message -----
From: "Duncan Murdoch" <murdoch.duncan at gmail.com<mailto:murdoch.duncan at gmail.com>>
To: "Chris Evans" <chrishold at psyctc.org<mailto:chrishold at psyctc.org>>
Cc: "r-package-devel" <r-package-devel at r-project.org<mailto:r-package-devel at r-project.org>>
Sent: Friday, 12 February, 2021 15:40:25
Subject: Re: [R-pkg-devel] How to build *-package description from *-package.R files ... and a luser/newbie question
about pkgdown
Just one clarification:
Regarding 'pkgdown', can't you just use the default directory , docs/, that pkgdown populates? When you push to your repository, github will automatically regenerate the pkgdown website (for this to work, you need to go to the settings on your github repo and activate building the website).
As to documentation, go to the github site of pkgdown and start from there. To customise the site, you can add an yaml file, as documented in pkgdown.
I am not sure why you wish to use DIY directory for the site generated by pkgdown. When you run build_site(), pkgdown builds it and opens it in a browser by default. Also, it only rebuilds the pages that have changed since the previous built. So, it is useful also during development. I don't remember at the moment if you could even set it up to watch for changes in the package and rebuild the site behind the scene.
Georgi Boshnakov
-----Original Message-----
From: R-package-devel <r-package-devel-bounces at r-project.org> On Behalf Of Duncan Murdoch
Sent: 12 February 2021 13:50
To: Chris Evans <chrishold at psyctc.org>; r-package-devel at r-project.org
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
______________________________________________
R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Please note that most rooygen2 users don't call the overview file 'pkgname-package' but just 'pkgname'.
Also, these days people mostly use README.md for approximately that purpose and put a very minimal statement in pkgname-package or equivalent.
Georgi Boshnakov
-----Original Message-----
From: R-package-devel <r-package-devel-bounces at r-project.org> On Behalf Of Chris Evans
Sent: 12 February 2021 15:52
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: r-package-devel <r-package-devel at r-project.org>
Subject: Re: [R-pkg-devel] How to build *-package description from *-package.R files ... and a luser/newbie question about pkgdown
Apologies, I think that was clear.
Do you or anyone else have an example of a ****-package.R that Rstudio's check has built into a package documentation file that was well populated and useful?
I think that's the key exemplar I am seeking and I'm finding it hard to craft any web search that finds me such a thing.
Any offer?! TIA,
Chris
----- Original Message -----
From: "Duncan Murdoch" <murdoch.duncan at gmail.com>
To: "Chris Evans" <chrishold at psyctc.org>
Cc: "r-package-devel" <r-package-devel at r-project.org>
Sent: Friday, 12 February, 2021 15:40:25
Subject: Re: [R-pkg-devel] How to build *-package description from
*-package.R files ... and a luser/newbie question about pkgdown
Just one clarification:
On 12/02/2021 9:59 a.m., Chris Evans wrote:
[ lots deleted ]
- 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?
No, I use RStudio. When I said "I don't use it much", I meant Roxygen2.
Duncan Murdoch