mountainMath / mountainMath/cansim

Onboard the three build-ignored vignettes to CRAN

Open Beginner friendly
#171 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
R
Stars
51
Forks
6
Avg merge
15h 34m
Merged PRs (30d)
1

Description

Three vignettes are excluded from the build by .Rbuildignore, so CRAN users
never see them:

vignettes/listing_cansim_tables.Rmd
vignettes/retrieving_cansim_vectors.Rmd
vignettes/working_with_hierarchies.Rmd

Six vignettes exist; three ship. browseVignettes("cansim"),
vignette(package = "cansim") and the CRAN landing page list only
cansim, partial_table_data_download and working_with_large_tables.

The three that are missing arguably cover the material a new user needs
first — finding a table, pulling a single vector, and navigating dimension
hierarchies. They are only visible on the pkgdown site, which is exactly the
audience least likely to need them, since anyone who reached the pkgdown site
has already found the documentation.

The reason for excluding them no longer applies
  • 425f3e2 (2018-12-09, "reduce built vignettes") added the three
    .Rbuildignore lines. At the time every chunk was evaluated at build time,
    so each vignette meant a round of NDM downloads on every CRAN check.
  • 334d3cb (2021-04-23) gave every vignette, shipped and excluded alike,
    eval = nzchar(Sys.getenv("COMPILE_VIG")) in its setup chunk. Compare with
    1d7a2dd, "disable running of examples and vignettes. running them causes
    problems at CRAN as it will throw an error when Statistics Canada servers
    are down or otherwise temporarily unavailable."

Since 2021 the vignettes have therefore knitted code-only on CRAN, with no
network access and no evaluation. The COMPILE_VIG guard solved the problem
that motivated the exclusion, but the .Rbuildignore lines were never
removed.

Cost

All three are already written as proper vignettes — full \VignetteIndexEntry
and \VignetteEngine headers — so onboarding them is deleting three lines from
.Rbuildignore. Nothing else changes.

They add 314 lines of .Rmd. Rendering with COMPILE_VIG unset, on an M-series
Mac:

vignette status build
cansim shipped 17.6s
partial_table_data_download shipped 7.6s
working_with_large_tables shipped 15.5s
listing_cansim_tables excluded 16.6s
retrieving_cansim_vectors excluded 10.6s
working_with_hierarchies excluded 14.4s

Roughly 41s today, roughly 83s with all six. That is R startup and pandoc, not
evaluation — there is no network traffic in any of it, so the failure mode that
prompted 1d7a2dd cannot recur.

Suggestion

Drop the three lines from .Rbuildignore and ship all six. Worth a check with
--as-cran afterwards to confirm the index entries are picked up cleanly, and
a _pkgdown.yml glance to make sure the articles list still reads sensibly.

If some of them are deliberately kept web-only for a reason not in the git
history, it would be worth a comment in .Rbuildignore saying so, since the
current state reads as an oversight.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with .Rbuildignore and the three listed vignette paths: vignettes/listing_cansim_tables.Rmd, vignettes/retrieving_cansim_vectors.Rmd, and vignettes/working_with_hierarchies.Rmd. Remove their exclusion lines, then run the suggested --as-cran check with COMPILE_VIG unset and glance at _pkgdown.yml. Done means all six vignettes build and appear in the package index without network evaluation.

Written by the indexing model from the issue text.

Assessment

Tech stack
r
Domain
build-system, documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
92/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.