Expand Quick Start guide with web scraping example and bundle setup - #153
Merged
Conversation
A Recipe needs the sum of what its plugins need, and in a source checkout that sum is a list of Bundler groups rather than a list of gems. Nothing said so end to end: the table listed each plugin's group, and an operator running a three-plugin Recipe still had to discover, one failed run at a time, that `html` alone gets past CustomFeedWeb and stops at StoreDigest. doc/DEPLOYMENT.md takes one Recipe -- CustomFeedWeb, StoreDigest and PublishMarkdown -- from written to running in seven steps beside the table it reads from, and adds why a checkout resolves through the bundle at all, what the missing-gem message does and does not mean there, which commands answer "what does this bundle hold", and when to select `plugins` rather than the groups a Recipe names. The other three documents gain a pointer each and no second copy. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019fgz9HsShz5W9ytoVms5BH
The old first run was chosen so that nothing had to be installed for it, which taught the one thing a second Recipe immediately un-teaches: almost every useful Recipe names a plugin with an optional gem, and working out which gems from which plugins is the step that stops a first run half way through. Teaching it in step 4 of the guide, on a Recipe that needs it, is better than leaving it to be discovered. The Recipe is CustomFeedWeb, StoreDigest and PublishMarkdown over four public index pages: no account, no credential and no service, but two optional gems, arrived at by reading the Recipe plugin by plugin against the table in doc/DEPLOYMENT.md. The checkout section is then the same step done with Bundler groups, and doc/DEPLOYMENT.md keeps the reasoning that belongs to a checkout. Consistency, since "the Quick Start needs no optional gem" was an assertion made in several places: README's summary of it, the note in PLUGINS.md 6.7 and in publish/markdown.rb explaining why PublishMarkdown carries its own HTML reduction, the spec that guards the shipped feed2markdown example, and RELEASING's smoke test, which tests an installed gem with no optional dependency and is described as that now. No behaviour changes, so no Updated:: line moves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019fgz9HsShz5W9ytoVms5BH
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
2 participants
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.
This PR significantly expands the Quick Start documentation and related guides to provide a more comprehensive first-run experience, particularly for users working with source checkouts.
Summary
The changes transform the Quick Start from a minimal example using only built-in dependencies into a complete walkthrough that includes installing optional gems and demonstrates the full workflow of setting up a Recipe with plugin dependencies. A new detailed section in DEPLOYMENT.md explains how to determine and install the gems a Recipe needs.
Key Changes
Documentation Updates:
web2markdown.ymlRecipe that scrapes four public index pages (Python, Rust, Go, and JPCERT/CC) instead of just fetching an RSS feed. The guide now includes explicit steps for identifying and installing required gems (nokogiri,activerecord,sqlite3), with emphasis on understanding why a Recipe needs the sum of all its plugins' dependencies.bundle exec, and whygem installis not enough here" explaining the distinction between gem installation and bundle resolution in checkouts.Code/Config Updates:
feed2markdown.ymlis a shipped example that requires no optional gems, distinguishing it from the new Quick Start Recipe.Key Documentation Insights:
gem install(RubyGems) and bundle group selection in checkoutsPublishMarkdownneeds no optional gems despite being used in the example, teaching users to consult the dependency table rather than guess from plugin functionalityNotable Details
CustomFeedWebto demonstrate HTML parsing,StoreDigestfor deduplication, andPublishMarkdownfor outputbundle config,bundle show, andbundle exec rubyto verify bundle statewith plugins) for development vs. only Recipe-needed gems for production usehttps://claude.ai/code/session_019fgz9HsShz5W9ytoVms5BH