Skip to content

Rework the documentation and site for 3.0.0 - #16

Merged
elkronos merged 25 commits into
mainfrom
docs/site-rework
Nov 12, 2026
Merged

elkronos merged 25 commits into
mainfrom
docs/site-rework

Conversation

@elkronos

Copy link
Copy Markdown
Owner

Reworks the documentation and the pkgdown site ahead of 3.0.0, so that every page states what the package does now and the articles follow the order in which the pipeline runs.

Site organisation

  • Articles: nine, in four groups.
    • Get started.
    • Step by step: Choosing a resolution, Cells, Spatial cross-validation, Models and Reporting.
    • Worked example: North Carolina.
    • Help: Troubleshooting and Glossary.
  • New articles: Cells, Troubleshooting and Glossary.
  • Models: replaces Diagnostics. articles/diagnostics.html now redirects to articles/models.html.
  • Reference index: 14 sections that follow the pipeline, from "Start here" to "Set options, catch conditions and clear caches". The old reference addresses now redirect.
  • Home page: a short path from installing the package to a first scored result.

Content

  • Help pages: each page states the current behaviour in the present tense. Version history moved to NEWS. Three shared topics replace the boilerplate that had been pasted onto many pages: input geometry, condition classes and options.
  • Articles: every number comes from inline R, so the text matches the output.
  • Figures: figures that no code or script could trace were removed.
  • NEWS: the 3.0.0 entry is an upgrade guide.
    • Its Breaking changes section opens with the defaults that change results, each with the argument that gives back the 2.0.0 result.
    • Bug fixes are grouped by function.
    • The entry went from about 94,000 words to about 9,900.
  • Example scripts: the scripts in inst/scripts are updated to match the current API.
  • Tests: the tests that pin documentation text now check the new text. No behavioural assertion was relaxed.
  • CI: job and setup-step timeouts, so a runner that hangs fails within minutes instead of hours:
    • 15 minutes for setup-r;
    • 40 minutes for the dependency install;
    • 60 to 150 minutes per job.

Checks on this branch

Check Result
macOS test suite, strict mode 0 failures
Linux test suite in the CI image 0 failures, 305 test files
R CMD check --as-cran 0 errors, 0 warnings
spelling::spell_check_package() clean
pkgdown::check_pkgdown() and a full site build pass
Internal links in the built site 0 broken
document() and build_readme() leave the tree unchanged

The check's NOTE includes five README links that return 404 until this branch is merged and the site deploys:

  • articles/cells.html
  • articles/glossary.html
  • articles/models.html
  • articles/troubleshooting.html
  • .github/CONTRIBUTING.md

Left for later

  • The pkgdown development: mode: auto key: added at the 3.0.0 version bump.
  • Long print lines in a few print methods: wrapping them is deferred until after 3.0.0, because exact-line print tests and the frozen baseline pin the current output.

The rules for reading input geometry, the condition classes and the two
work-limit options were spread over the argument entries and sections
of many help pages. Three topics now hold them in one place:
?spatialkit-geometry (CRS alignment, layers without a CRS, mixed
dimensions and M, rows without a location, boundaries, polygons in
degrees), ?spatialkit-conditions (every class the package raises, who
raises it, what it means, what to do, the fields it carries and how to
catch it) and ?spatialkit-options (spatialkit.exact_pairs_max and
spatialkit.fit_work_max). Each statement is checked against the code.
The home page now leads with what the package does, installs from CRAN
first, and runs a quick start that draws Voronoi cells at the default
count and compares random with blocked cv_rf() scores, with every
number computed when the page is knitted. A pipeline map and one table
of articles replace the function table, the backend guide, the
troubleshooting and operations notes and the duplicate documentation
list, which move to their own articles and to a contributing guide.

The Scope section now says the Bayesian backend fits binary, ordinal
and categorical responses. The resolution figure is rebuilt around the
default count with its leave-one-out errors, and the folds figure is
drawn side by side. DESCRIPTION describes the default cell count and
the pooled value and cites kNNDM. inst/CITATION gives each method its
own entry.
?spatialkit now opens with where to start, lists the eleven pipeline
steps with the article for each, and names resolution_profile() and
select_resolution() as the route to a cell count. Migration notes and
version history leave the help for NEWS; uncited defaults are listed
as such.

?resolution_profile, ?select_resolution and ?determine_optimal_levels
get headed sections, a Value written as lists, their own conditions
only, links to the shared geometry and conditions topics, and examples
that print what their comments describe. Simulation figures no script
reproduces are cut. ?ensure_projected says what target_crs does to
input that is already projected. coerce_to_points() documents each
mode, and its line_midpoint error names the argument `mode`.
Get started now installs from CRAN first and holds the one table of
optional packages, with a note on the Stan toolchain. Its first step
chooses the cell count with resolution_profile() and
select_resolution(), and every count and score in the prose and the
map's alt text is computed from the output, so the page no longer
says eight cells where it draws seven. It names which functions take
a logical, factor or character response and which refuse one, drops
the claims that predict_surface() takes a raster and that the
reporting article fits on cells, and gives the R2 of both fold
schemes with the forest's out-of-bag R2. Warnings the text names are
shown, each optional-package chunk leaves a note when the package is
missing, the scripts table moves here from the home page, the
earlier-defaults paragraph goes to the changelog, the glossary moves
to its own page, and a Next section replaces the article list.
Retitle it "Exporting and reporting results" and order it as the cells
as a file, a cell mean, a pooled cell value, a model's score and what
to save. Correct what the code contradicts: sites need no reprojection
before a membership lookup, a negative R2 is against the training
mean, get_voronoi_seeds() is unseeded by default, three report lines
are computed checks, and a shapefile renames most columns. Add a table
of seed arguments, a saveRDS() record, the surface with its flag, and
compute every count inline. Drop the date line, the closing printout
of package versions and the earlier-defaults paragraph, and link the
other articles for detail.
?summarize_by_cell now opens with its output columns, then pooled
values, intervals, standard errors and design effects, and conditions,
and gathers its simulation figures in one section that links the script
that makes them. Figures that no script in the repository reproduces
are cut, and the column names, cell_weight and id_col are described as
the code returns them.

The other cell-building and assignment pages lose their version history
and the repeated boundary rules, which ?spatialkit-geometry now holds,
and the longest ones gain headed sections. Titles start with a verb.

create_grid_polygons() takes a selection, a profile or ranked levels as
target_cells, as build_tessellation() does, and logs when n overrides
target_cells. plot_tessellation_map() reads ID columns in the order the
join reads them, and the kriging_adequacy() report wraps to the console
width.
?make_folds opens with what it returns and where the result goes, then
a table of the six methods, and moves block sizing, NNDM, kNNDM and the
numerical tolerances into headed sections, so each argument states only
its contract. ?estimate_sac_range gets headed sections in reading order
and absorbs ?print.sac_range; ?cv_block_size_sweep absorbs the plot
method. ?cv_spatial holds one text for folds, boundary, pointize and the
fold-size arguments, which cv_gwr() and cv_bayes() inherit, and lists
its return value element by element. Input-geometry rules link to
?spatialkit-geometry; version history and measured figures with no
script behind them are gone; examples print every value their comments
name.

plot_folds() now gives the size of the blocks it draws beside the
block_size asked for, with no scientific notation, and draws its axes
in the projected CRS of the map; the variogram and sweep plots name the
CRS's linear unit in short form; the sweep's printed table and the
directional ranges of print(<sac_range>) fit 80 columns.
The help pages of the fitters, the methods on a fit, the in-sample and
cross-validated comparisons, predictor selection, prediction and the
area of applicability state the current behaviour, without version
history or simulation figures that no script reproduces. The predict,
fitted, residuals and coef methods of the three backends share one page
per verb with a runnable example, and the families follow the reference
sections. Fixes: a literal \% that cut lines on ?area_of_applicability,
the `...` text of predict() for GWR and Bayesian fits, the GWR fitted()
description, coef() logging rather than warning, n_pred in the shared
metrics section, and the Bolin and Wallin reference. Plot labels no
longer clip or show Markdown backticks, and resolution profile panels
get fewer, shorter y labels.
The article is retitled "Worked example: North Carolina" and opens with
one sentence linking Get started in place of the overview list and the
note on earlier defaults. The modelling half now runs fit and residuals,
then spatial folds, then the surface, with a bridge from cells to
points. Every number the runs produce is computed inline, the closing
summary that contradicted the fold_separation() reading is gone, and the
comparison and area of applicability use the folds that reading
matches. Adds the variogram plot and a GWR coefficient map, sizes maps
for the state's shape, cuts explanations other pages own to links, and
drops the date line, em dashes and sessionInfo().
The Diagnostics article becomes "Fitting and checking models"
(vignettes/models.Rmd). It now covers choosing a backend, which moves
here from the home page without its outdated timings; the random
forest, GWR with a map of its local intercept, and the Bayesian GP as
shown code; writing a backend with new_spatial_fit(); scoring all of
them on the same blocked folds; residual Moran's I and what to do when
it is large; choosing predictors inside the folds, with the nested run;
and the area of applicability, computed with the folds and followed by
what to do outside it. Every number in the prose is computed on the
page. The cell sections leave for the cells article.
The spatial cross-validation article now opens on the built-in cv_*()
functions, cuts the custom learner to its constructor and predict(),
and gives the four fold_separation() readings with a clustered example
where random folds read closer and kNNDM folds match the map. It runs
kNNDM, buffered leave-one-out and Voronoi blocks, prints the blocks
built beside block_size, draws the variogram, checks each sweep size
against the map, shows the warnings it describes, and ends with the
next article and the method references. Every number is computed.
The package's core step had no article of its own: tessellation
methods, standard errors and the design effect, the kriging check and
the pooled-value warnings were spread over four pages. The new article
"Building cells and summarising them" takes them in pipeline order,
from choosing a method and placing seeds to cell values at other
locations. It corrects the design-effect and kriging wording, shows
the warnings as R prints them, and computes every count inline.
The article now opens with what the cell count controls and the default
call, then covers a size for pooled values, leave-one-out for plain
means, a ladder of counts with its bounds before the criteria, an elbow
from the coordinates (with a clustered example that finds one), choosing
on one half, and passing the count to the cells.

It corrects the claim that a profile's levels share one random stream,
says which count arguments take a selection, gives the full ceiling and
structure rules, and prints every warning its prose names, the default
rule on a ladder of counts among them. It says a bound chose the count
only when one did, uses "flat region" throughout, links the simulation
script, and drops the date line and an unsourced cross-validation claim.
Troubleshooting and performance takes the README's troubleshooting and
practice sections: each message is quoted as R prints it, the examples
print real output, and a table gives the work limits a large layer
meets, each read from the code. It also covers parallel folds, the two
caches and the log file's path. Terms used on these pages is the
glossary from Get started, with the block entry corrected and the terms
the other pages use added.
The reference index now has the pipeline's sections in order, each with
a verb-first title and a description, with seed placement and the
lower-level builders as subsections under Build the cells. The Articles
menu groups the nine articles as Get started, Step by step, Worked
example and Help, and the old Diagnostics page redirects to the models
article. KaTeX renders the formulas that reference pages showed as LaTeX
source, and the options section now says when each cache needs clearing.
The workflow comments name the articles each job runs in full.
The tour scripts and the North Carolina script described defaults by
how they differed from earlier versions, used " -- " as a dash, and
gave a few numbers and behaviours the code no longer bears out: the
fitted ranges of the fixture, a k reduction said to raise no warning,
and what n_local_singular counts. They now state current behaviour in
the site's terms and spelling, give distances in metres, and quote the
numbers a run prints. example_nc_demo.R follows the reworked North
Carolina article step for step, with the same folds and numbers.
The development entry becomes the 3.0.0 entry: an opening paragraph,
Breaking changes led by the defaults that change results and the
argument that restores each, the new functions with the article that
shows them, bug fixes a 2.0.0 user could meet merged by theme, and a
short Documentation section. Entries sit under the reference index's
section titles, ordered by function name, and none runs past 120
words. The 2.0.0 entry keeps its substance without the dashes and the
notes on how the release was written.
The help pages, articles and changelog were rewritten, so thirteen
test files still pinned the sentences they replaced. The help and
article pins now read the new text: predict_surface, ensure_projected,
assign_features_to_polygons, resolution_profile, the boundary rules
in ?spatialkit-geometry, the condition list in ?spatialkit-conditions
and the troubleshooting article. Pins on changelog wording are gone;
one check that Breaking changes holds the adapt_delta entry stays.
Every behavioural assertion is unchanged.
The tests that read help pages, articles, the README and the scripts
now look for the sentences where they stand after the rework: the
fold-reading sentences on their new pages, the seeders' boundary rules
in "Sampling inside the boundary", the sweep plot in its section of
?cv_block_size_sweep. Phrases reworded without a direction word leave
the exception list, and the checks on changelog wording go. Prints of
kriging_adequacy() are read unwrapped, the plot caption without
backticks, and tessellation labels in the ID column order of the join.
Eleven test files read help text that the reference rework moved,
split or reworded. Their assertions now match the new sentences,
including the rules now stated once on ?spatialkit-geometry, and
assertions on changelog wording are gone. Two tests read output whose
format changed: the kriging check's report, now wrapped at the console
width, is read at a wide one, and the plot_cv_metrics() captions are
matched without the backticks ggplot2 drew as plain text.
The help pages now link the shared geometry topic, state current
behaviour without version history and keep no unsourced lattice counts.
These tests now read the new text, check that ?spatialkit points to
Breaking changes in NEWS, and print kriging_adequacy() wide so its
wrapped report lines stay whole. Assertions on NEWS wording go; the
behavioural assertions are unchanged.
The documentation tests read the help pages, vignette sections and NEWS
entries that describe pooled values. They now find those texts under
their new titles, including the "How this was checked" sections and the
cells article, and keep the three rules: the denial sentence wherever
an interval is described, no figure that is not a row of
dev/sim-pooled-values.csv, and no existing units named. Checks on NEWS
wording and on help paragraphs that were removed go with them. The
reference helpers and their tests describe each reference by what it
computes, with the code unchanged, and inst/WORDLIST lets
spelling::spell_check_package() run clean.
A read of the built site found statements the code contradicts and
pages that are hard to use. The design-effect, glossary, cv_spatial()
and README cell-ID claims now match the code; a help paragraph that
rendered as a code box renders as prose; long Value sections become
lists; each article links its first use of a term to the glossary and
states optional packages one way; models gains a map of the masked
surface; wide tables scroll at phone width. Prints lose a "WSS rises
at 0 step(s)" clause and the "levels in band" label, give the
area-of-applicability distance in the CRS unit, and show record errors
in one notation without forcing 9.52 into 9.52e+00. Tests and 52
frozen records follow the new print text, and builds from a worktree
leave out its .git file.
A network failure on the runner image kept setup-r retrying apt for 92
minutes before the job failed. Each R setup step now stops after 15
minutes and each dependency install after 40, and every job has a
limit well above its usual run time: 120 minutes for the check matrix,
150 for the optional backends and the nightly brms check, and 60 for
the site build.
The test fitted a random forest without checking for ranger, which is
in Suggests, so it errored on the check jobs that install only the
required packages. The unit and CRS checks now run first and the
forest caption check skips when ranger is missing.
@elkronos
elkronos merged commit 7c00ba7 into main Nov 12, 2026
9 checks passed
@elkronos
elkronos deleted the docs/site-rework branch November 12, 2026 18:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant