Skip to content

fix(docs): repair the frameworks.svg comment and clarify the image footer - #178

Merged
FabianClemenz merged 1 commit into
mainfrom
docs/image-footer-wording
Sep 14, 2026
Merged

FabianClemenz merged 1 commit into
mainfrom
docs/image-footer-wording

Conversation

@FabianClemenz

Copy link
Copy Markdown
Member

Summary

Two small fixes to the launch image, one cosmetic and one an actual defect.

1. frameworks.svg was not well-formed XML

When the generator script was dropped in #176, I added a header comment to the SVG documenting how to re-export the PNG. That comment contained uv run --group docs … — and XML comments may not contain a double hyphen, so the file stopped parsing.

Invisible on the site, which serves the PNG, and mkdocs build --strict never noticed because it treats the SVG as an opaque asset. But the file I documented as "the editable source" would not open in a browser or a vector editor. Found while re-rendering it.

The comment is rewritten without literal flags, spells the re-export out as Python instead, and says why:

Note: XML comments may not contain a double hyphen, so command line flags are
spelled out in prose above rather than shown literally.

xml.etree.ElementTree.parse() now accepts the file.

2. The footer arithmetic

The headline reads "Five frameworks. One diagram." while the footer listed six items:

SQLModel · SQLAlchemy · Django · Pydantic · dataclasses · SQL DDL

Both were defensible — SQL DDL is an input format, not a Python model framework — but a reader scanning a thumbnail counts the footer and sees a number that contradicts the headline. On an image whose job is to be trusted in two seconds, that is an own goal.

Now: … dataclasses · **and raw SQL DDL**. The "and" marks it as a different category, so the count reads as five frameworks plus something else.

The claim itself is still correct

Checked rather than assumed. MODEL_SOURCES is unchanged at exactly five, and every classification path returns one of them:

MODEL_SOURCES = ("sqlmodel", "sqlalchemy", "django", "dataclass", "pydantic")

--base-classes (#173) did not add a sixth: a ninja.Schema subclass is classified as pydantic. django-ninja support rides on an existing framework rather than being a new one, so "five" is right and "six" would have been wrong.

The README already says "5 Python Frameworks + SQL DDL" and the docs home says "five frameworks plus raw SQL DDL" — both precise. Only the image blurred the distinction.

Type of change

  • Bug fix
  • Documentation

Verification

xml.etree.ElementTree.parse() on the SVG succeeds (it did not before). PNG re-rendered at 1600×840 and inspected. mkdocs build --strict passes; full pre-commit run --all-files clean.

Checklist

  • Tests added or updated for the change — n/a, docs asset
  • uv run pytest passes locally
  • uv run ruff check src/ tests/ and uv run mypy src/ pass
  • Docs/README updated if behavior changed
  • CHANGELOG.md updated under [Unreleased]

…oter

The header comment added when the generator script was dropped contained a
command-line flag. XML comments may not contain a double hyphen, so the file
stopped parsing as XML — invisible on the site, which serves the PNG, but the
file documented as the editable source would not open in a browser or editor.
Rewrite the comment without literal flags and note why.

Also: the footer listed SQL DDL as a sixth bullet under a headline counting
five frameworks. SQL DDL is an input format, not a Python model framework
(MODEL_SOURCES is still exactly five), so it now reads "and raw SQL DDL" and
the two numbers no longer look like they disagree.
@FabianClemenz FabianClemenz added bug Something isn't working documentation Improvements or additions to documentation labels Sep 14, 2026
@FabianClemenz
FabianClemenz requested a review from a team as a code owner September 14, 2026 13:04
@FabianClemenz
FabianClemenz merged commit 9fe5fc4 into main Sep 14, 2026
12 checks passed
@FabianClemenz
FabianClemenz deleted the docs/image-footer-wording branch September 14, 2026 13:05
@FabianClemenz FabianClemenz mentioned this pull request Sep 14, 2026
6 tasks done
FabianClemenz added a commit that referenced this pull request Sep 14, 2026
## Summary

Patch release. `[Unreleased]` → `[0.14.1]` with the compare link,
version bump, `uv lock`, and the documented pre-commit `rev:` moved to
`v0.14.1`.

### What ships

**Fixed — ninja `ModelSchema` no longer drawn as an empty entity**
(#179). Behaviour introduced hours ago in 0.14.0: anyone passing
`--base-classes ModelSchema` got an empty box beside the real table. Now
detected, skipped, and explained on stderr.

**Fixed — `frameworks.svg` is valid XML again**, and the image footer no
longer makes the headline's "five" look like a miscount (#178).

**Changed — the README and docs home open with the five-frameworks
image** (#176–#178).

### One reclassification worth noting

The `ModelSchema` entry moved from `### Added` to `### Fixed`. It stops
erdify producing a wrong entity rather than adding a capability — and
getting that right is what makes this a **patch** rather than a minor. A
reader scanning the changelog for "do I need this?" gets a truthful
answer either way, but the version number only lines up under `Fixed`.

### Why release now rather than sit on it

Two reasons, and the second is the stronger one:

1. **It fixes output that is wrong today.** `--base-classes` shipped in
0.14.0, so the empty-entity bug is live for anyone who reaches for
`ModelSchema`.
2. **The PyPI page is a launch landing page, and it is stale.** PyPI
renders the README from the sdist at publish time. 0.14.0 was published
*before* the five-frameworks image and the comparison table landed, so
pypi.org/project/erdify currently shows neither. With Show HN and
r/Python next on the list, the page people hit from those posts should
be the current one.

Nothing in here is risky: one narrow parser guard with 7 tests, and
documentation.

## Type of change

- [x] Refactor / maintenance

## Verification

```
uv run pytest                 348 passed
uv run ruff check / mypy      clean
uv run erdify --version       erdify 0.14.1
mkdocs build --strict         passes
pre-commit run --all-files    clean
```

`uv.lock` re-synced in the same commit.

## After merge

Same flow as before: I tag `v0.14.1`, publish the GitHub release and
post the announcement Discussion. The PyPI publish then waits in the
gated `pypi` environment for your **Review deployments → Approve**.

## Checklist

- [x] Tests added or updated for the change — n/a, release mechanics
- [x] `uv run pytest` passes locally
- [x] `uv run ruff check src/ tests/` and `uv run mypy src/` pass
- [x] Docs/README updated if behavior changed
- [x] `CHANGELOG.md` updated under `[Unreleased]`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant