Hypster Documentation Audit

A small, single-maintainer Python config framework hosted on GitBook. The skeleton is sensible — Getting Started, In-Depth, Concepts — but the load-bearing pages on the landing route and the conceptual reference are largely empty containers, the install instructions contradict the landing page, and a key Getting Started page truncates mid-section.

1. Landing "How Does it work?" stepper has headings but no content (critical)

Location: https://gilad-rubin.gitbook.io/hypster (home)

Problem: The rendered home page enumerates five steps — "Install Hypster", "Define a configuration space", "Explore your configuration", "Instantiate your runtime object", "Execute!" — but every step body is empty in both the rendered DOM and the llms-full.txt mirror. The llms-full.txt view confirms this is not a scraper artifact: it explicitly shows {% step %} **Install Hypster** {% code overflow="wrap" %} with no fenced code that follows, then proceeds to the next step heading.

Consequence: The first impression page promises a 5-step quickstart and delivers chapter titles. A new user (or an AI coding agent indexing the entry page) cannot copy a working "hello world" without leaving the home page and hunting through Getting Started. Agents pulling llms-full.txt get the structure but no executable content for the very example the home page advertises.

The fix: Inline each step's actual code snippet on the landing stepper, or replace the empty stepper with a single linked "5-minute Quickstart" page that contains complete copy-pasteable Python.

2. Home page promises a pip install but the install page only documents uv (significant)

Location: https://gilad-rubin.gitbook.io/hypster (home, "Install Hypster" step) and https://gilad-rubin.gitbook.io/hypster/getting-started/installation

Problem: The home page reads "Or using pip:" — implying a uv command followed by a pip alternative. The Installation page, however, only contains a section titled "Install With uv" and no "Install With pip" counterpart in the scraped content. The home page's pip reference therefore points at no actual pip instruction on the canonical install page.

Consequence: Developers without uv installed (the larger Python population in 2026 is still a mix of pip/poetry/uv) hit the install page expecting parity and get one tool's worth of guidance. Agents extracting the install command can't decide which package manager is canonical.

The fix: Add an explicit pip install hypster block on the Installation page (and any conda/poetry guidance if supported), or remove the "Or using pip" teaser from the home page if uv is intentionally the only supported install path.

3. Concepts/Articles page is a one-link stub (significant)

Location: https://gilad-rubin.gitbook.io/hypster/concepts/articles

Problem: The "Articles" page reads in full: "These articles explain the ideas and use cases that led to Hypster." followed by a single external Medium link titled "5 Pillars for a Hyper-Optimized AI Workflow". No second article, no inline summary, no excerpt.

Consequence: A page promoted as conceptual background is effectively an outbound redirect. Readers who click through lose the docs context; readers who don't never learn the framework's rationale. This is also the kind of page LLM agents will weight heavily when asked "why use Hypster?" and they'll get one Medium URL instead of an answer.

The fix: Either inline an executive summary of the "5 Pillars" article (with the Medium link as a "read the full essay" footer), or delete the page and link the article directly from the home page's positioning section.

4. In-Depth reference page renders ## Signatures with no body (significant)

Location: https://gilad-rubin.gitbook.io/hypster/in-depth/hp-call-types/text-and-multi-text

Problem: The Textual Types page introduces hp.text() and hp.multi_text(), then opens a ## Signatures section with no scraped content beneath it. The page implies a signature reference exists but the body is empty in the fetched DOM.

Consequence: This is the in-depth reference — the page a developer or agent lands on after Getting Started to find the actual parameter names, types, defaults, and return values. An empty "Signatures" section under a function-reference heading is the worst-case state: it advertises an authoritative definition and supplies none. Agents will return "documented but unspecified" for these calls.

The fix: Populate ## Signatures with the actual Python signature for each function, an example per signature, and any raised exceptions. Audit the sibling hp-call-types/* pages for the same empty-heading pattern.

5. Getting Started "Instantiate and Replay" page truncates mid-section (significant)

Location: https://gilad-rubin.gitbook.io/hypster/getting-started/instantiating-a-configuration-space

Problem: The page introduces instantiate() and then opens a ## Unknown Parameters section whose visible content ends at "Unknown or conditionally unreachable values raise by default:" with no example, no code block, and no continuation. The page stops at the colon.

Consequence: This is the same empty-heading pattern as Issue 4 but on a Getting Started page, which makes it more damaging — it's earlier in the funnel, and the missing content is precisely the behavior a developer needs to understand (what raises, what doesn't, and how to handle it) before reaching for the in-depth pages. Agents indexing the Getting Started tree will see a section heading and infer documented behavior that isn't actually documented.

The fix: Complete the ## Unknown Parameters section with the actual raised exception type, a minimal example that triggers it, and the recommended handling pattern. Sweep the rest of Getting Started for the same truncation shape.

6. No machine-readable API reference for an SDK-shaped product (significant)

Location: Site-wide (no /api, /reference, OpenAPI, or generated pdoc/sphinx-style reference visible in the scraped tree)

Problem: Hypster is a Python SDK whose surface, per the scraped pages, includes at least hp.text, hp.multi_text, instantiate(), and explore(), plus any other hp.* calls the library exposes. The scraped content shows narrative pages per type but no consolidated reference — no auto-generated API index, no per-function table of parameters/defaults/returns, no __all__ listing.

Consequence: Developers cannot answer "what are all the hp.* calls?" without crawling the sidebar one page at a time. Agents have no single index page to consume, so they can't reliably enumerate the SDK surface. For a library whose value proposition is "Pythonic API + Type Safety", the missing reference is the missing receipt.

The fix: Generate a /reference/ tree from docstrings (pdoc, mkdocstrings, sphinx autodoc) or hand-author a single "API Reference" page that lists every public hp.* call, instantiate, explore, and their full signatures. Link it from the top of the In-Depth section and include it in llms-full.txt.

7. "Define a Config Function" page is prose-only with no example (significant)

Location: https://gilad-rubin.gitbook.io/hypster/getting-started/defining-a-configuration-space

Problem: The page describes a configuration space in prose — "A Hypster configuration space is an ordinary Python function whose first argument is named hp. It is not a DSL or a separate config file format: use normal Python control flow, lists, helper functions, imports, and object construction." — but the scraped excerpt contains no example of what such a function actually looks like. For the "Define a configuration space" step in the funnel, that is the example.

Consequence: A reader who arrived here from the empty home-page stepper (Issue 1) lands on the page that should make the framework concrete and finds another prose-only definition. Copy-paste is impossible; agents extracting "show me a config function" will return the sentence above instead of code.

The fix: Add a complete, runnable example showing a def my_config(hp): ... body that uses at least one hp.* call, followed by an instantiate() invocation and its return value. If the scraped excerpt was truncated, confirm the live page actually contains an example and surface it earlier.

8. Home page advertises "Native, first-class optuna support" with no corresponding docs page (significant)

Location: https://gilad-rubin.gitbook.io/hypster (home, "Key Features" list)

Problem: The Key Features list claims "🧪 Hyperparameter Optimization Built-In: Native, first-class optuna support." No optuna integration page, tutorial, or reference appears anywhere in the scraped tree — not under Getting Started, In-Depth, or Concepts.

Consequence: The feature most likely to attract ML practitioners is asserted on the landing page and undocumented everywhere else. Anyone who picks Hypster for the optuna story has no documented path to use it; agents asked "how do I use Hypster with optuna?" have nothing to retrieve and will either fabricate an answer or punt.

The fix: Add a dedicated "Hyperparameter Optimization with Optuna" page covering the integration entry point, a minimal end-to-end example (config space → search → best params), and any constraints. Link it from the Key Features bullet on the home page.

9. llms-full.txt exists but mirrors the same empty stepper as the rendered page (minor)

Location: https://gilad-rubin.gitbook.io/hypster/llms-full.txt

Problem: Good news first: llms-full.txt is published, which puts Hypster ahead of most small dev-tool docs for agent consumption. However, the file faithfully reproduces the home page's empty {% step %} blocks — the agent-oriented surface inherits the same content gaps as the human-facing one.

Consequence: Agents that prefer llms-full.txt for indexing will index the holes. Having llms-full.txt is currently a structural win and a content wash.

The fix: Once the home stepper (Issue 1) is populated, regenerate llms-full.txt so the agent-readable mirror carries the same code. Consider also publishing a separate llms.txt (short index) pointing at the populated reference pages.

Open Questions (not yet verified)

• The home page advertises "Tutorials" and "Best Practices" cards in its "Discover Hypster" section, but no /tutorials or /best-practices routes were fetched. These may exist and simply weren't in the scrape, or they may be stubs of the same shape as Concepts/Articles. Worth verifying directly before publishing as a finding.

What they do well

• llms-full.txt is published — most small Python libraries don't bother, and Hypster does. Once the underlying pages are filled in, the agent story is half-built.
• The information architecture is sensible: Getting Started → In-Depth → Concepts is a defensible spine for a small SDK.
• Constraints are stated upfront (Python 3.10/3.11/3.12, no runtime deps) on the Installation page — exactly where they should be.

Top 3 recommendations

1. Fill the home-page stepper with actual code, or replace it with a complete quickstart page. The empty stepper is the single most damaging gap because it's the first thing every reader (and every agent) sees.
2. Finish the truncated and empty section bodies — ## Unknown Parameters on the Instantiate page, ## Signatures on the Textual Types page, and the missing example on "Define a Config Function" — and sweep the rest of Getting Started and In-Depth for the same pattern.
3. Add a consolidated API reference covering every public hp.* call plus instantiate and explore, and back the home page's "first-class optuna support" claim with a dedicated integration page.