Skip to content

Onboard the three build-ignored vignettes to CRAN #171

Description

@mountainMath

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions