enhance docs - #120
Merged
Merged
Conversation
KotlinIsland
force-pushed
the
enhance-docs
branch
5 times, most recently
from
August 4, 2026 01:24
f671210 to
d04c34a
Compare
charliecloudberry
approved these changes
Aug 4, 2026
KotlinIsland
force-pushed
the
enhance-docs
branch
from
August 4, 2026 01:33
d04c34a to
49843ee
Compare
move breaking changes into features as "differences from python" the old title was awkward and the page does not belong at the top level — it is reference material, so it sits in the feature reference under a new "python compatibility" section adds lazy-by-default imports, which belonged in the runtime-behaviour list from the start: an import with a side effect no longer runs just because the module was loaded the `is not` warning in getting started goes with it — that is fixed now reverse-transpile python's `is not` to `!==` `by transpile --reverse` left `a is not b` untouched, and `is not` means *not an instance of* in basedpython — so transpiling the result forward turned an identity check into `not isinstance(a, b)`, silently. only `is not None` came out right, and only because the operator was never touched at all the literal guard now mirrors the forward transform on both operators, so `is None` / `is not 1` stay as they are: identical in both languages, and churning them would be noise. `not isinstance(x, y)` also reverses to `x is not y` now rather than the clumsier `not x is y` the operator is located by scanning tokens rather than searching text, so a comment threaded through it can neither hide the `not` nor be swallowed by the replacement — that case was the same silent break in miniature use a realistic __eq__ in the py-to-by example the old one called isinstance on a value it had just identity-compared to self, which is nonsense. an __eq__ with an identity fast path is where both actually appear in python, and it exercises the same reverse transforms verified against the binary, both directions typeshed improvements, breaking changes to python, py-to-by, and credits typeshed improvements lists every patch the vendored stubs carry, split into the ones that change what a type means and the ones that only change how it reads breaking changes to python collects the places the same source reads differently, so renaming a .py to .by is an informed decision getting started gains a py -> by section. the example is the real output of `by transpile --reverse`, which is how it caught that `__init__` and `Optional[T]` have no reverse transform acknowledgements is folded into credits implementations ships, so drop the planned section `implementation A for B` has a 523-line transform, a 683-line mdtest suite and an `invalid-implementation` diagnostic. extensions.md and conversions.md already cross-reference it as a real feature; only the index still called it planned it now sits next to extensions, the feature it is closest to — both give an existing type new members from the outside drop backticks from nav labels, and the ships-today note and under-the-hood section nav labels are plain text, so a backtick rendered as a backtick the development pages the under-the-hood grid pointed at are all still in the nav, so nothing is orphaned by removing it lead the readme and docs index with what basedpython is, and add credits the four capability lines the project leads with, plus a note on which of them are in a release — `by compile` and wheel packaging live on an unmerged branch, so an unqualified claim would send people to a subcommand that does not exist credits names the people who build basedpython. it is separate from acknowledgements, which is specifically about third-party code the transpiled output imports at runtime scope RUF012 out of the pygments lexer and reformat the lexer check a pygments lexer's api is its class attributes, so RUF012 does not apply to it. `uvx prek run -a` reports this where the pinned `prek` run did not syntax highlighting and a redesign for the basedpython docs every `by` code block rendered as undifferentiated plain text, because pygments has no lexer for basedpython. adds one as `python/basedpython-pygments`, wired into the docs dependency group through a pygments entry point the lexer approximates basedpython's soft keywords with per-keyword lookaheads mirroring the position each is legal in, so `data class Point` is a modifier while `def f(data: bytes)` is a parameter. `scripts/check_by_lexer.py` runs it over all 508 `by` blocks in the docs and over a table of keyword and non-keyword snippets the site itself was running on stock theme defaults: no repo link, no code copy button, no prev/next, no breadcrumbs, and a flat ninety-item feature nav. enables the theme features the reference actually needs, groups the feature nav by the sections its index already had, and rewrites the landing, feature, framework and getting-started pages around cards, tabs and admonitions
KotlinIsland
force-pushed
the
enhance-docs
branch
from
August 4, 2026 01:35
49843ee to
7f6a265
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
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.
No description provided.