animint2 Reference Website

[ampurr]

Here's the thread that will track the development of the animint2 reference website. 🐈

[ampurr]

@tdhock, sorry—I'm gonna ask you to do something for me. I would do it myself, but I don't have security clearance (or whatever it's called). 😅

Could you go to Settings > Pages and deploy the GitHub Pages site from the reference-website-yay branch? Later on we'll probably start deploying from the main branch and automate things with GitHub Actions (unless you don't want to).

But for now I just wanna set up a preliminary site in your repo instead of my fork. Also, usethis::use_pkgdown_github_pages() doesn't work unless GitHub Pages is set up.

Thanks! As always, no rush. :>

[tdhock]

I did that, does it work for you?

[ampurr]

Thanks! Lemme run the pkgdown stuff and play around. I'll you know as soon as I do plus a delay of perhaps up to several minutes, since instantaneous communication is impossible. :>

[ampurr]

Hmm. When you deployed the site, in

Settings > Pages > Build and deployment > Source,

are you using GitHub Actions or are you deploying from the reference-website-yay branch?

[tdhock]

It says Deploy from a branch, is that ok? Can I give you access some how so you can do this config?

[ampurr]

Yeah, deploy from a branch should be right. Weird that it works from my fork but throws up a GitHub API error (404): Not Found error when I do it from my branch in this repo. I'll figure it out.

Feel free to give me access, and I'll happily return it when the GitHub Pages site is set up. But I'm not sure how to do it. Maybe give me admin powers? I can't find anything about whether admins have power over setting up Pages, though. If you have more modular control, feel free to give me access only to the Pages settings or something. But I haven't been able to find anything about that.

[ampurr]

Yeah, deploy from a branch should be right. Weird that it works from my fork but throws up a GitHub API error (404): Not Found error when I do it from my branch in this repo. I'll figure it out.

Hypothesis: I'm using my personal access token, which maybe probably doesn't work for this repo since it's not mine. I may need you to generate a token for this repo and send it to me.

When I started this project, I had no idea it would require so many tedious little tasks from you, which I apologize for. Do you think I should continue this stuff from my fork instead? Of course, that has other problems and probably increases your future workload in exchange for a reduced workload now. :thinking:

[tdhock]

OK thanks for the info. I'm not sure how to give you admin access, because I think github changed their web site since the last time I did that. I don't know if this will help, but I saw a message saying "create an organization to grant access controls" so I created the animint organization, and invited you.

[ampurr]

Thanks! I joined but the animint organization doesn’t seem to have access to any repositories. I don’t know if it’s because the animint2 repo wasn’t added, or if it’s cuz I’m missing some sort of permission. Either way: I don’t get access to the settings for animint2 and therefore can’t control the stuff about pages.

Don’t worry about it, though. If it’s okay with you: I can just do stuff on my fork and at some later date we can have an electron meeting and figure it out this GUI stuff together. And I can just merge my fork into a branch here later, too.

[tdhock]

hi @ampurr and @Faye-yufan I gave you admin access to this repo (recently transferred to animint/animint2 from tdhock/animint2) does that work for you?

[ampurr]

@tdhock: It works! Thank you very much. :>

[Faye-yufan]

Hi @tdhock , yes it works, thank you!

[ampurr]

Status update: I'm currently working on editing README.md, which will serve as the home page for the animint2 reference site, and which @tdhock suggested that I edit during our last meeting. (It is currently a mirror image of README.org.)

If there's anything I should really make sure to include or exclude, please let me know. 🐱

[tdhock]

for sure include screenshots, installation, and basic usage example. anything else you want to delete please move to a wiki page.

[ampurr]

Okay, will do! What do you mean by "anything else you want to delete please move to a wiki page"?

[tdhock]

There is a wiki on this github repo, https://github.com/animint/animint2/wiki and you could move the README section "Differences with Other Packages" to a new wiki page with that name.

[ampurr]

Sorry, I'm still confused. My fault, not yours. But I took some time to think about it and I'm less confused than before.

So I'm going to try and say what I'm doing. And then I'm going to say some possible interpretations of what you're requesting. Then you can let me know if any of the interpretations are correct.

I generated README.md from README.org. I'm editing README.md, which does not affect README.org. My goal is to have the animint2 reference site homepage look different from the GitHub README. GitHub will read from the Org file, while the website will get its homepage from the Markdown file. (I'll rename README.md to index.md to prevent a conflict.)

I'm confused partly cuz I'm not deleting anything from README.org, so it's unclear what the benefit of adding parts of it to the animint2 wiki are.

Some interpretations:

1. You want the Org and Markdown READMEs to be in sync. That's why I need to move some deleted parts to the wiki.
2. The Org and Markdown READMEs cannot be in sync. You want the information present in the Org file but excluded from the Markdown file to be part of the wiki.
3. My status update was unclear, and your request is based on an assumption that I'm unaware of.

EDIT: Interpretation 2 said the READMEs were in sync when they should've said they cannot be in sync. Whoops.

[tdhock]

yes for 1, and actually just delete the org file in your PR please.

[ampurr]

Understood. Will do. Thanks for clarifying. :>

[ampurr]

Today I learned that I do not know how GitHub's milestone thingy works.

[ampurr]

Status update: added the "Differences with other packages" section from README.org to the animint2 repo wiki. I'll be linking that wiki page on the animint2 reference homepage.

No plans to add anything else to the wiki.

[ampurr]

Minor status update: I'm unable to include basic usage examples in the README. Why? GitHub doesn't support JavaScript in its READMEs, and animints are made of sugar and spice and also JavaScript. I'm moving the examples to a vignette and including a link in the Use section.

[ampurr]

Status update: work on the examples vignette is going all right. The biggest difficulty is selecting a built-in dataset that shows off animint2's features. I've tried morley and Theoph, but they're too sparse to display the faceted graphs well. Will probably try msleep next.

[ampurr]

Status update: work on the examples vignette is going all right. The biggest difficulty is selecting a built-in dataset that shows off animint2's features. I've tried morley and Theoph, but they're too sparse to display the faceted graphs well. Will probably try msleep next.

Just simulate the data. You’re demonstrating some package features, not doing science. 😛

[ampurr]

Status update: what was meant to be a brief short examples section has expanded into a quick start guide for animint2. The simulated data idea has worked out, though it took some time to shape the data so that they aren't too random or too perfect.

The most difficult aspect of the quick start guide is explaining something like the grammar of graphics without actually relying on the grammar itself. Mostly cuz I'm worried the grammar adds too much unneeded complexity for something that a new user's meant to understand in, like, 10 minutes.

I'm unsure of this decision. It's possible that not explaining the grammar is a bad idea. Advice is welcome—no pressure if you don't have any.

[tdhock]

sounds good to me

[ampurr]

Okay, cool. :>

[tdhock]

can you share a link to your current draft reference website / quick start guide?

[ampurr]

Would you like me to commit what I currently have in a branch and send you the link?

The stuff I've committed so far is in the reference-website-yay branch. I haven't committed the current README.md and quick-start.Rmd (and website_setup.Rmd) files yet, though. Why? They're either in various states of incompleteness or dissatisfactory-ness.

EDIT: Whoops. Accidentally referred to website_setup as website-setup. Typo fixed.

[ampurr]

Status update: I've completed my draft for the quick start guide. Lemme know what you think. Harsh criticism is welcome. There will likely be some intense editing in the future regardless. So no worries if you don't wanna comment.

I spent a lot of time experimenting with <table> and display: flex; to try and hack together a ggplot2-style facet, but that didn't work out, and there's no trace of it in the current draft.

I wanna say that I anticipate a working website by the end of the week. But I've been terrible at estimating how long things will take in this project. 🐈

[ampurr]

Oh, I forgot to mention. Something I wanna do is to explain how to use clickSelects. (Currently, only showSelected is explicitly used.) Part of the pedagogical difficulty is:

1. There's already an implicit clickSelects active when you use animint().
2. Explicitly declaring clickSelects doesn't seem to be useful unless your data are super dense, like with the World Bank data.

[ampurr]

Status update: the new README.md is done. :>

[ampurr]

Status update: animint2's functions are being reorganized in the _pkgdown.yaml file. 🧹

[ampurr]

Status update: animint2's functions have been reorganized. Currently, pkgdown::build_site() throws up an error,

Error in yaml.load(readLines(con, warn = readLines.warn), error.label = error.label,  : 
(./_pkgdown.yml) Parser error: while parsing a block mapping at line 9, column 1 did not find expected key at line 53, column 1

which has not previously shown up. So I probably messed up the syntax somewhere. Trying to figure it out. :>

[ampurr]

Status Update

Skimming through the YAML specifications, I learned that whitespace is syntactically significant in YAML files... except when it's not? Cool cool cool.

Anyway, I figured out the parser error. It was a typo. -title: "Adjustments" should have been - title: "Adjustments". Whoops. There's that significant whitespace. 😅

Using check_pkgdown() throws up new errors:

Error in `map2()`:
ℹ In index: 2.
Caused by error in `purrr::map()`:
ℹ In index: 4.
Caused by error:
! In '_pkgdown.yml', topic must be a known selector function
✖ Not 'gg-add'
Caused by error in `gg - add`:
! unused argument (add)
Run `rlang::last_trace()` to see where the error occurred.

Which is progress! :>

[ampurr]

Status update: Resolved the new errors. Three of the topics were under the wrong name. So I fixed that. But it also turns out that I missed about 50 topics, so I'm gonna add them. Figured I'd miss some on my first go, but not that many. 😅

@tdhock, two (or more) of those topics aren't functions and should instead be vignettes. They are translate_qplot_ggplot and translate_qplot_lattice [1]. They come from ggplot2, though they and qplot() have since been deleted from the Tidyverse. Should I leave the translate-* functions as topics, change them into vignettes, or delete them outright? Or do something else? Thanks. :>

[1] translate-qplot-ggplot & translate-qplot-lattice

[ampurr]

Status update: All 50 aforementioned topics have been added. Unfortunately, this does mean I'll need to re-organize the functions again. Previously, the categories were dissatisfactory. Now, they're dissatisfactory and also messy and hard to navigate and probably aesthetically displeasing.

For example, one section looks like this:

- title: "Animint & Animint Helpers"
  desc: >
    ...
- contents:
  - starts_with("animint")
  - addShowSelectedForLegend
  - addSSandCSasAesthetics
  - starts_with("check")
  - colsNotToCopy
  - starts_with("get")
  - issueSelectorWarnings
  - make_bar
  - make_tallrect
  - make_widerect
  - make_text
  - merge_recurse
  - newEnvironment
  - parsePlot
  - pt.to.lines
  - renderAnimint
  - saveChunks
  - selectSSandCS
  - setPlotSizes
  - split_recursive
  - switch_axes
  - varied.chunk

I think I'll probably break that into two subsections at minimum.

translate_qplot_ggplot and translate_qplot_lattice have been placed under title: internal, which just means that they're out of the public eye till I get some more guidance about what to do about them. 🐈

[ampurr]

Status update: Working through _pkgdown.yml. I think the functions have mostly been reorganized, and I'm writing and editing the descriptions for the different sections. Feeling pretty good about that. A little uncertain about the "Animint Helpers" section, since there's so many functions in it [1]. But maybe sections can have lots of functions in them and that's okay. Let me know if you disagree, of course.

[1] It looks like this:

- subtitle: "Animint Helpers"
  desc: >
    ...
- contents:
  - addShowSelectedForLegend
  - addSSandCSasAesthetics
  - starts_with("check")
  - colsNotToCopy
  - starts_with("get")
  - issueSelectorWarnings
  - make_bar
  - make_tallrect
  - make_widerect
  - make_text
  - merge_recurse
  - newEnvironment
  - parsePlot
  - pt.to.lines
  - renderAnimint
  - saveChunks
  - selectSSandCS
  - setPlotSizes
  - split_recursive
  - switch_axes
  - varied.chunk

[ampurr]

Addendum: Thoughts on adding your YouTube video to the README? Didn't realize this video existed till now. :O

[ampurr]

Also, lemme know if you want a News section on the website. If so, I'll convert NEWS to NEWS.md and make some changes to the formatting.

[ampurr]

Status update: _pkgdown.yml is complete and also hopefully full of useful comments. The resulting reference page looks good. :>

[tdhock]

all this sounds good but I still am unable to preview the web site, even after clicking the links you provided in comments above. if you can not provide a link to preview, can you please provide instructions about how you are viewing the site, that I could follow?

[ampurr]

Hey, Toby. :>

The links are to the code or markup that'll produce the website, not to the website itself. Should they normally allow you to preview the website? I'm less familiar with GitHub than you are, so please let me know if I've messed something up re: previewing the website. 😅

If you wanna wait, I'm planning on throwing the website online today. And you can view it from there and suggest changes.

If you don't, you can build the website yourself by:

1. Cloning the website branch (reference-website-yay)
2. install.packages(pkgdown)
3. pkgdown::build_site()

Hope this helps. Let me know if I've misunderstood your message. 😺

[ampurr]

Oh, I should clarify the pkgdown website situation.

How do I build a website and ask GitHub to throw it online for me? There are two methods:

• Build the website with pkgdown::build_site(), which will produce a bunch of HTML files in a /docs directory. Then commit that directory and its contents to git.
• Build the website, but don't commit the directory to git. Instead, set up a GitHub Action to build it for you.

To be honest, I've never gotten the second method to work before on my personal websites. But I'm probably gonna try it anyway. If it fails, I'll just go to the first method.

Let me know if you have any preferences or if I should just do whatever. Thank you. :>

[ampurr]

Here it is: https://animint.github.io/animint2/

EDIT: This was done via the first method. As mentioned, I've never gotten the second method to work, and I'm really not sure how. I'm unfamiliar with GitHub Actions. Even if I did get it to work, I think it'd count as cargo cult programming.

EDIT 2: The animints don't seem to be showing up... I'll look into that.

[ampurr]

Note to self: The rendered HTML does include <script> tags that refer to what animint2 should've outputted. Some of the output doesn't seem to exist. I wonder why. pkgdown outputs static plots from animint2...

[ampurr]

Note to self: pkgdown writes the JavaScript for the first R code block, but none of the other code blocks. Untested wild hypothesis—pkgdown loads code blocks independently from one another, unlike how most R Markdown and Quarto files do it.

[ampurr]

Minor status update: pkgdown exhibits a bug where ![alt text](image_file) causes the alt text to also appear in the fig caption. I've bypassed it by replacing the Markdown image syntax with an HTML <img> instead.

Planning on creating a reproducible example and filing a bug report with the pkgdown people.

[ampurr]

Also! Getting pretty close to finishing this up. Lots of little stuff left, but we have a working website and all. So the big stuff seems finished. Though let me know if you disagree, of course.

Checklists to keep myself organized:

Fix Alt Text Redundancy so it Stops being Redundant

• [x] Fix alt text–fig caption duplication problem.
• [ ] Create reproducible example. See here for an example of how to do it.
• [ ] Create issue on r-lib/pkgdown. Link reproducible example.

Animints Need to Show Up in the Quick Start Guide

• [x] Take a look at Debugging from Advanced R.
• [x] Figure out why pkgdown renders code chunks 1-6, but fails to render any chunks afterward. Chunk 6 was the first animint thing. (Never mind. It's just rendering in the wrong folder.)
• [x] Figure out why the rendered code chunks fail to produce the interactive JavaScript data viz that it should. (Didn't succeed.)
• [x] Fix the problem. Possible solution: render everything manually and force it onto the page with <script>s. But it's obviously better if I can get pkgdown to do it instead.

Writing is Important and so is Documentation

• [x] Look over and edit README.md.
• [x] Look over and edit the quick start guide.
• [x] Finish up the website setup page.
• [x] Look over and edit the website setup page.

I Like it When Websites are Pretty

• [x] Touch up the website's CSS. That includes: link colors, padding between sections, and font size.
• [ ] Create an interactive hexagon badge for the Animint2 package.
• [x] Add the tests passed GH badge back to the README.
• [x] Add code annotations to the codeblock in the quick start guide.
• [x] Improve spacing between animints and paragraphs.

Stop Pretending to be a Digital Hermit

• [x] Concatenate the questions you've asked in this thread. Discard the irrelevant ones and present the relevant ones to Toby.
• [x] Get Toby's feedback on the website as a whole.

You Have Other Issues

• [ ] Close issue #100. Add the TODOs.
• [x] Close issue #96. Look into it. If that's not possible, close.

[ampurr]

Note to self: the code chunks are now being rendered with JavaScript and everything. But the JS isn't rendering on the page.