Skip to content

docs: Derive README.md from a README.Rmd - #609

Open
krlmlr wants to merge 13 commits into
claude/readme-goalsfrom
claude/readme-rmd
Open

docs: Derive README.md from a README.Rmd#609
krlmlr wants to merge 13 commits into
claude/readme-goalsfrom
claude/readme-rmd

Conversation

@krlmlr

@krlmlr krlmlr commented Sep 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

The hand-written README.md kept this package out of the shared rendering pipeline. This PR adds a README.Rmd copied from it verbatim, prefixed with the output: cynkratemplate::readme_document front matter and the canonical generated-file comment, and re-renders with cynkratemplate::render_readme().

Rendering also writes index.md for pkgdown — the README.md without the code-of-conduct footer. Both README.Rmd and index.md are added to .Rbuildignore; R CMD build plus tar tzf confirms the tarball ships only README.md.

The rendered README.md differs from the hand-written one only in pandoc's gfm normalisations:

  • the generated-file comment at the top;
  • * bullets written as -;
  • ```R written as ``` r;
  • a blank line after <!-- badges: start -->, after ## Installation, and before ## Connecting to a specific Postgres instance;
  • a trailing space stripped from the R-SIG-DB line, and a trailing empty line dropped from the end of the Heroku connection snippet;
  • --- written as a full-width row of hyphens;
  • and, since feat: Autolink inline code in the README's prose cynkra/cynkratemplate#135, inline code in prose linked to its reference page: Redshift(), postgresImportLargeObject() and postgresWaitForNotify(), all under https://rpostgres.r-dbi.org/reference/.

I checked this mechanically: the multiset of words in the old and new README.md is identical apart from the added comment and the markup tokens above, and every URL that was there is unchanged. No evaluated chunks were added — this is a faithful derivation, not new content.

The README contains no evaluated chunks, so rendering needs no database server. Rendered twice with the current cynkratemplate, the second time in a differently named directory with another time zone and locale, both outputs are byte-identical to the committed file, and a further render changes nothing. With README rendering in CI becoming the default, this is what CI will produce.

Stacking

This derivation logically belongs below the line-break work, but it is stacked on top of claude/readme-goals to avoid rewriting and force-pushing every branch in the open chain across four repositories.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m

@krlmlr krlmlr mentioned this pull request Sep 13, 2026
Open
@krlmlr
krlmlr force-pushed the claude/readme-rmd branch 2 times, most recently from 7e03121 to fc9461c Compare September 13, 2026 20:30
@krlmlr
krlmlr added this pull request to stack #611 September 13, 2026 21:05
krlmlr and others added 10 commits September 14, 2026 07:27
@krlmlr @claude
docs: Use pak::pak() for the development install
5c9240c 
One of the items `usethis::use_tidy_upkeep_issue()` prescribes for 2023.
`pak::pak()` resolves system requirements and installs binaries where they exist,
so it does not need a compiler for pure-R dependencies the way `install_github()` does.

The `# install.packages("pak")` comment is kept, matching what the packages in this fleet that already use pak do.
Both usethis and devtools import pak, so most readers already have it,
but a reader with neither of those installed still needs the line.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@krlmlr @claude
docs: Point the coverage badge at the branch that exists
9d6e367 
Closes #599.

The badge image was pinned to `branch/master`, which has not existed since the rename to `main`.
Codecov kept serving that branch's last recorded figure while `main` moved on,
so the image disagreed with the link beside it, which already pointed at `main`.

The branch is dropped from the image URL rather than corrected to `main`.
A branch-pinned badge goes stale silently the next time a branch is renamed, which is exactly what happened here;
without one, codecov reports the default branch and the badge follows a rename on its own.

The link becomes `app.codecov.io/gh/r-dbi/RPostgres/tree/main`:
the `app.` host is the UI (the bare host serves the badge image),
`/gh/` is the canonical short form,
and `/tree/main` is the branch view rather than the `?branch=` query that redirects to it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@krlmlr
docs: Break lines at meaning boundaries
184b665 
Reformatting only, no wording changes: prose in README.md, the
vignette and the roxygen and inline comments under R/ now breaks at
sentence and clause boundaries rather than wrapping to a fixed width.

The payoff is sentence-level diffs. A reworded sentence touches one
line instead of reflowing the paragraph around it, so review sees the
change and not the rewrap.

man/*.Rd is regenerated because roxygen2 passes source line breaks
through to the .Rd. The rendered help is byte-identical -- checked with
tools::Rd2txt() over every topic -- as is the rendered README.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@krlmlr
docs: Start every broken sentence on its own line
caeda09 
A sentence that spans more than one line now starts at the beginning of
a line, and so does the sentence after it. Line breaks only, no wording
changes.

Where two sentences are separated by two spaces, the pair stays on one
long line: roxygen2 strips leading and trailing whitespace from
continuation lines, so a break at that gap would drop a space from the
rendered help.

man/*.Rd is regenerated because roxygen2 passes source line breaks
through to the .Rd. The rendered help is byte-identical -- checked with
tools::Rd2txt() over every topic.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@krlmlr
docs: Indent continuation lines to keep sentence spacing
7defa71 
Inside a roxygen block the first line of a paragraph, and every tag line,
keeps one space after `#'`; every continuation line of that paragraph now
has two. The paragraph structure of the source becomes visible without
reading ahead, and in packages that do not enable roxygen2 markdown the
extra space is what carries a sentence gap across a line break.

RPostgres enables markdown (`Roxygen: list(markdown = TRUE)`), and commonmark
strips leading whitespace from a paragraph's continuation lines, so here
the indent reaches neither `man/*.Rd` nor the rendered help. Nothing is
regenerated: roxygen2 writes no file, and `tools::Rd2txt()` is unchanged
for every topic.

That also means the one long line this pass created cannot come apart
again. `R/dbConnect_PqDriver.R` keeps the sentence pair that the
previous commit joined on a single line, because under markdown no
leading-space, trailing-space or hard-break form survives into the
`.Rd`, so breaking there would drop a space from the rendered help.

The generated `R/cpp11.R` is left untouched.

Reformatting only, no wording changes: the words either side of the diff
are identical once comment markers and whitespace are collapsed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@claude
docs: Drop the continuation-line indent
9b57e03 
The two-space continuation indent never reached the `.Rd`. RPostgres sets
`Roxygen: list(markdown = TRUE)`, and commonmark strips the leading
whitespace of a continuation line before roxygen2 writes the topic, so the
indent changed no rendered output -- `man/` was byte-identical with it and
without it.

The sentence gap it was meant to carry now comes from roxygen2 itself
(krlmlr/roxygen2#8), which indents the line break after a sentence at the
point where the break is emitted. The source-level indent is redundant, so
it comes out.

This is `git revert` of the indent commit, not a substitution: that pass also
normalised pre-existing three-space tag continuations down to two, and the
revert puts them back at three.

The long joined lines the sembr pass created stay as they are. Undoing those
is a separate decision, and the roxygen2 fix is what will eventually let them
come apart.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@krlmlr
docs: Break the joined sentences apart
80569b8 
The long joined lines existed to protect a sentence gap:
two spaces after a sentence period are content, Rd2txt() renders them literally, and a line break there drops one of them.
Joining the sentences onto one line was the only way to keep the gap.

The joins come out, so every sentence starts its own line again.

Reformatting only, no wording changes.

man/ is left to CI, which regenerates it from these sources.

A line break which follows the end of a sentence currently renders as one space rather than two.
Restoring that gap needs a patched roxygen2, which is a separate decision and a separate pull request,
so it is deliberately not part of this change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@krlmlr
chore: Auto-update from GitHub Actions
d8f290e 
Run: https://github.com/r-dbi/RPostgres/actions/runs/34782806136
@krlmlr @claude
docs: State the goals and non-goals
3c59035 
Scope drawn from the README's own opening and its "Design notes" section
("This turns out to be too general: a driver has no real state, for PostgreSQL
each connection can only have one result set ... the driver class is just a
dummy class with no contents"), the DESCRIPTION (Imports DBI, bit64, blob, hms,
lubridate; SystemRequirements names libpq >= 9.0), the exported
PostgreSQL-specific helpers in NAMESPACE (postgresWaitForNotify(),
postgresImportLargeObject(), Redshift()), and tests/testthat/test-DBItest.R,
which runs DBItest::test_all().

The type-mapping goal claims a best fit rather than a lossless one.
src/PqResultImpl.cpp maps NUMERIC and MONEY to double, and INTERVAL and UUID to character,
so "without losing information" would not hold.

The Redshift non-goal names BLOBs only, which tests/testthat/helper-DBItest.R
still records as `omit_blob_tests = TRUE` in its Redshift context.
NEWS.md 1.4.0 also reported limitations enumerating temporary and persistent tables,
but 1.4.3 supersedes that entry: "Temporary tables are now discovered correctly
for `Redshift()` connections, all DBItest tests pass".

The "does not bundle a client library" non-goal says that no libpq source ships with the package,
rather than that the build relies on the system libpq.
The latter holds on Unix only: tools/winlibs.R downloads a prebuilt libpq on Windows,
and configure falls back to autobrew on macOS.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@claude
docs: Derive README.md from a README.Rmd
5e87678 
The hand-written `README.md` keeps the package out of the shared rendering pipeline,
so this adds a `README.Rmd` copied from it verbatim,
prefixed with the `cynkratemplate::readme_document` front matter and the canonical generated-file comment.

Rendering with `cynkratemplate::render_readme()` also writes `index.md` for pkgdown,
which is the `README.md` without the code-of-conduct footer.
Both `README.Rmd` and `index.md` are added to `.Rbuildignore` so neither ships in the tarball.

The rendered `README.md` differs from the hand-written one only in pandoc's gfm normalisations:
the generated-file comment, `*` bullets written as `-`, ` ```R ` written as ` ``` r `,
blank lines inserted around headings and `<!-- badges: start -->`, trailing whitespace stripped,
and `---` written as a full-width row of hyphens.
No word, URL, or code-block content changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@claude @krlmlr
docs: Derive README.md from a README.Rmd
1587ada 
The hand-written `README.md` keeps the package out of the shared rendering pipeline,
so this adds a `README.Rmd` copied from it verbatim,
prefixed with the `cynkratemplate::readme_document` front matter and the canonical generated-file comment.

Rendering with `cynkratemplate::render_readme()` also writes `index.md` for pkgdown,
which is the `README.md` without the code-of-conduct footer.
Both `README.Rmd` and `index.md` are added to `.Rbuildignore` so neither ships in the tarball.

The rendered `README.md` differs from the hand-written one only in pandoc's gfm normalisations:
the generated-file comment, `*` bullets written as `-`, ` ```R ` written as ` ``` r `,
blank lines inserted around headings and `<!-- badges: start -->`, trailing whitespace stripped,
and `---` written as a full-width row of hyphens.
No word, URL, or code-block content changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@claude
Merge remote-tracking branch 'origin/claude/readme-rmd' into claude/r…
4a95e8e 
…eadme-rmd
@claude
docs: Render README.md with the autolinker
5fb6669 
The format from cynkratemplate#135 now links inline code in prose to its reference page,
and this branch was rendered before that landed,
so the committed README.md no longer matched a fresh render.
With the README rendered in CI by default, the first run would have committed the links itself;
this commits exactly what that run produces, so the pull request stays a faithful render.

Only README.md changes: the links are added to prose and nothing else moves.
index.md is untouched, because pkgdown links the front page itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@krlmlr @claude