docs: group pkgdown Reference into thematic sections#107
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR improves the pkgdown documentation site’s Reference index by introducing a _pkgdown.yml configuration that groups exported functions into thematic sections, making the API easier to discover for new users.
Changes:
- Add
_pkgdown.ymlto define five thematic groups for the pkgdown Reference index. - Update
.Rbuildignoreto exclude_pkgdown.ymland any locally generateddocs//pkgdown/directories from the built package tarball.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
.Rbuildignore |
Ignores _pkgdown.yml plus docs/ and pkgdown/ so pkgdown artifacts/config don’t enter the package build. |
_pkgdown.yml |
Defines grouped Reference sections covering all current NAMESPACE exports. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| desc: > | ||
| High-level entry points that produce a `Dockerfile` object, | ||
| either from a project descriptor (DESCRIPTION, renv.lock) or | ||
| by parsing an existing Dockerfile file. Most users start here. |
The pkgdown site auto-generated a single flat list of all exports. With nine entries spanning three distinct conceptual layers (high- level builders, R6 class, helpers), a new user landing on the Reference index could not tell at a glance where to start. Group the Reference index into five small sections so the "start here" surface (the three `dock_from_*` / `parse_dockerfile` builders) stays at the top, the low-level R6 class lives on its own, and the sysreqs / project-setup helpers sit on the side. `_pkgdown.yml` is added to `.Rbuildignore` so it does not bloat the package tarball; same for any future `docs/` or `pkgdown/` directories pkgdown might generate locally. `pkgdown::check_pkgdown()` validates clean.
VincentGuyader
force-pushed
the
feat/pkgdown-reference-grouping
branch
from
07aae9e to
bb99525
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The pkgdown site auto-generated a single flat list of all exports.
With nine entries spanning three distinct conceptual layers (high-
level builders, R6 class, helpers), a new user landing on the
Reference index could not tell at a glance where to start.
This PR adds a
_pkgdown.ymlthat groups the Reference index intofive small thematic sections:
dock_from_desc,dock_from_renv,parse_dockerfile.Dockerfile.r.get_sysreqs,compact_sysreqs.docker_ignore_add._pkgdown.ymlis added to.Rbuildignoreso it does not bloat thepackage tarball; same for any future
docs/orpkgdown/directories pkgdown might generate locally.
Test plan
pkgdown::check_pkgdown()clean.sections (no missing, no double-listing).
R CMD check --as-cranunaffected (the new file is build-ignored).pr-reviewerapprove with one optional nit (the "builders"desc was tweaked to mention parsing, since
parse_dockerfileis a deserializer rather than a builder from a descriptor).
Context
Tier 5 polish item from the post-CRAN-prep roadmap, post-CRAN
nice-to-have. No code surface, no API change. The deployed site at
https://thinkr-open.github.io/dockerfiler/ will pick up the
grouping on next pkgdown CI run.