Improve documentation: nplot description, formula vignette, README, and pkgdown reference

[gvegayon]

This PR focuses on documentation and discoverability, as requested.

What's included

1. Better README

• New "Why netplot?" section framing what sets the package apart (beautiful defaults, formula-driven aesthetics, smart curved edges, grid integration, small dependency footprint).
• Expanded feature checklist (now including the formula interface, automatic legends, and gradient fills).
• README.qmd and README.md kept in sync (only prose changed, no code chunks).

2. Organized pkgdown reference

• New _pkgdown.yml groups exported functions by feature, with nplot on top as the main function. Groups: Drawing networks → Mapping attributes with formulas → Editing and querying a plot → Legends and color keys → Colors → Low-level drawing primitives → Base-graphics backend.
• Validated with pkgdown::check_pkgdown() (all exported topics accounted for).

3. Improved Rd files (roxygen)

• nplot()'s placeholder description ("This is a description.") is replaced with a real overview, plus a "Mapping attributes with formulas" section documenting vertex.color/vertex.nsides/vertex.size/edge.width formula support. Param docs updated (and propagate to nplot_base via @inheritParams).
• netplot-formulae (the ego()/alter() edge-color grammar) gains a details section and cross-links.
• Added a package-level help page (?netplot-package).
• The nplot() example now shows the formula interface.

4. New "formulas" vignette

vignettes/formulas.Rmd walks through mapping color, shape, and size from graph attributes, plus the ego()/alter() edge-color grammar and applying formulas after the fact with set_vertex_gpar(). Renders cleanly.

Suggestions for further improvements (not in this PR)

A few ideas that came up while reading the code, happy to open issues / follow-up PRs:

1. vertex.size = ~ f(attr) doesn't work — the formula RHS is taken literally as an attribute name, so ~ degree(x) fails. Supporting evaluated expressions (à la igraph/ggplot2 aesthetics) would be a nice ergonomic win.
2. Continuous-color / gradient legends — categorical vertex.color formulas draw a legend on print(), but numeric ones would benefit from a color-key legend (colorkey() already exists to build on).
3. Internal S3 methods lack export tags — roxygen2 (8.0.0) warns that get_vertex_attribute.*, get_edge_attribute.*, and color_nodes.* need @export/@exportS3Method/@noRd. Cheap cleanup to silence devtools::check() NOTEs.
4. color_nodes() is powerful but unexported — exposing it (or documenting vertex.color = color_nodes(...)) would let users control palettes/na_color directly.

Notes / please double-check

• I set the pkgdown site URL to https://usccana.github.io/netplot/ (standard GitHub Pages pattern for the USCCANA org) in both _pkgdown.yml and DESCRIPTION. Please adjust if the site lives elsewhere.
• Running roxygen2::roxygenize() (per the Makefile/AGENTS.md workflow) bumped the recorded roxygen version in DESCRIPTION (RoxygenNote → Config/roxygen2/version: 8.0.0) since 8.0.0 is installed locally, and normalized a couple of unrelated \link{} anchors in existing Rd files.

Testing

• tinytest suite: 22/22 pass.
• New nplot() Rd example and every vignette code chunk verified to run.
• pkgdown::check_pkgdown() passes.

🤖 Generated with Claude Code

[github-actions]

Thank you for your contribution @gvegayon 🚀! The pkgdown site preview is ready for review 👉 Download here 👈!
_{(The artifact expires on 2026-10-21T00:09:44Z. You can re-generate it by re-running the workflow here.)}

[gvegayon]

Round 2: formula fix, continuous legend, version bump

Follow-up to the review comments:

1. edge.width formula fix ✅

The root cause: plain edge.width = ~ weight actually worked, but any expression (~ log(weight), ~ weight * 2) failed with a cryptic the condition has length > 1. as.character(formula[[2]]) turns a call like log(weight) into c("log","weight"), and the attribute lookup then did c("log","weight") %in% names.

Fixed by evaluating the formula RHS against the graph's attributes (eval_attribute_formula() + all_graph_attributes()), so both bare names and expressions work for edge.width, vertex.size, and vertex.nsides. Missing attributes now give a clear error listing the available ones. Added regression tests (suite is now 26/26).

2. Discrete vs. continuous color legend ✅

vertex.color = ~ attr now auto-detects the attribute type and draws the appropriate legend on print():

• discrete (factor / logical / low-cardinality integer) → categorical key (as before)
• continuous (numeric / high-cardinality integer) → a color bar showing the scale

(Rendered both and verified visually.)

3. Flexible legend arrangement → issue #20 ✅

As suggested, the more advanced work — user-controllable legend placement and composing color + size + shape legends together — is tracked in #20 rather than done here.

4. Version bump to 0.4-0 + NEWS split ✅

DESCRIPTION → 0.4-0. NEWS.md now keeps only the four released items under 0.3-0; the previously-unreleased fixes plus this round's work are under a new 0.4-0 heading.

All tests pass (26/26); the formulas vignette re-renders against the updated package.