Feature request
jpiaskowski opened this issue · 15 comments
Would you be interested in deploying a pkgdown site for emmeans? I would be willing to make a pull request to facilitate this. I use this package a huge amount and would appreciate having all the document a bit easier to browse.
Also, what an amazing package! Thank you for all your work on this.
OK, I have looked at it a little bit. I apparently had it mixed up with packrat. If you're willing to make a PR, that definitely would speed this up as I have never done anything with pkgdown
I just want to second this. I have been thinking the same thing for years now as am I frequently teaching workshops that include {emmeans} and it is the only package in those workshops that does not have a typical pkgdown website documentation.
However, I never asked for it as I also myself wont find the time to make a PR.
I guess I had better "get with the program", as it were. But in a little bit as I have some other matters to attend to.
OK, well I tried just the default setup, and all went well for building the help files, but then when it got to build_article(), it choked with an incomprehensible error message. I imagine it doesn't like my custom CSS for vignettes. I tried adding
pkgdown:
as_is: true
to each vignette and that didn't help.
I'm afraid I am a pretty old dog, and not sure I can learn this new trick. And it is unacceptable to me to revert to the standard html_document format; I like the one I developed. So if there's no way around that, it won't get done.
I'll have a look. I run a pkgdown site with a small amount of custom css. Agreed, it's a headache, but not insurmountable. Ideally, we can establish a workflow so that the pkgdown site rebuilds automatically with each push/merged PR.
@jpiaskowski OK, thanks. I just (2024/05/02 9:30pm CDT) pushed to GitHub what I've done so far.
It looks like maybe what might work is to add this to each vignette:
html_document:
includes:
in_header: mystyle.html
where, somehow, I can get the following file named mystyle.html into the articles directory of the site (and docs directory of the built package):
<style type="text/css">
body {font-size: 11pt; font-family: "Palatino Linotype", "Book Antiqua", Palatino, serif;margin: 30px 50px 30px 50px; }
h1,h2,h3,h4,h5,h6 { font-family: Arial,Helvetica,Sans-serif; }
a { text-decoration: none; }a:link { color:darkblue; } a:visited { color:darkblue; } a:hover { color:dodgerblue; }a:active { color:dodgerblue; }
code {color: #602000;font-family: "Lucida Console", Monaco, monospace; font-size: 90%;}
.r { color: darkred; }
.ro { color: darkgreen; background-color: #eeeeee; }
.re { color: red;}
.r code, a code, .ro code, .re code { color: inherit; }
.vigindex ul { list-style-type: none; }.vigindex ul li { list-style: none; }.vigindex a code { color: inherit; }.vigindex li code { color: inherit; }
</style>
This of course is just my css code wrapped in a <style> block.
So how can I do that. Maybe a hint (in build_articles() documentation) is to give it a name starting in _? -- thus "enabling the use of child documents" according to that documentation.
Or can I just put it in inst/doc in my package code?
I have had success in creating a _pkgdown directory and putting the custom css code in there. 'pkgdown' looks there for custom css. That being said, I'm still having trouble building the site.
@jpiaskowski I think maybe your custom CSS was for the site, not for the articles.
I decided I could learn something by first ndoing a much simpler package of mine, estimability. That worked easily, and you can see the site here.
I also looked at my rsm package which I created long ago, using hard-coded vignettes. I see that my vignettes directory for that package has huge numbers of files in it, e.g. each of the figures. So I'm going to see if I can just put my file in there. If so, I really should have a pretty good chance of making my idea of a workaround pay off.
That's fantastic. Myself and many others are grateful for the effort you're putting into this.
OK, I can at least build the site. My custom function .emm_vignette() had a coding error that caused it to crash if the argument pandoc_args is passed to it. (Things always work better when you don't have bugs.)
So what we have now is that the actual vignettes in the package are formatted using my own style, but the "articles" on the site are formatted the way Hadley wants them.
@jpiaskowski OK, now I'm apparently out of my depth. I had previously built the site using build_site(), but now I'm trying to get the site to build automatically. I tried running usethis::use_pkgdown_github_pages() but it balks because it says upstream was not configured, and I need to configure a GitHub token. So I tried that...
> usethis::gh_token_help()
• GitHub host: 'https://github.com'
• Personal access token for 'https://github.com': <unset>
• To create a personal access token, call `create_github_token()`
• To store a token for current and future use, call `gitcreds::gitcreds_set()`
ℹ Read more in the 'Managing Git(Hub) Credentials' article:
https://usethis.r-lib.org/articles/articles/git-credentials.html
> gitcreds::gitcreds_set()
? Enter password or token: ghp_...<etc...copied and pasted from GitHub>
-> Adding new credentials...
-> Removing credentials from cache...
-> Done.
```But even after this, `use_pkgdown_github_pages()` fails the same way.
But I tried doing it manually anyway by adding jekyll_gh_pages.yml to my workflow. I noticed that the pkgdown GitHub site itself does not include the docs directory, so I moved that out of my project directory, figuring the workflow would build it. It doesn't. When I pushed it, I just get the README part of the site, not all the docs. What do I need to do?
yeah, github actions are a bit of a pain. I'll email you so we can walk through this over zoom.