docs: fix tensor shapes syntax to match shipped stubs

[Vishwaspatel2401]

Summary

The tensor shapes docs taught a shape syntax that the shipped
pyrefly-torch-stubs no longer accept: unbounded type parameters
(class Model[D]) and a flat multi-argument Tensor[D1, D2, ...] form.
Code written the way the docs showed it did not check.

This rewrites the affected pages to match what the stubs actually require:
IntVar-bounded type parameters and a single shape-list argument to
Tensor (Tensor[[D1, D2]]), matching the pattern already used in
torch-stubs/nn/__init__.pyi.

One page needed more than a bracket rewrap: the variadic-dimension
convention. The docs taught a bare TypeVarTuple (def forward[*Bs](..., x: Tensor[*Bs, D])), which doesn't just need brackets — it fails outright
under the current stubs (Unpacked type in IntTuple must use Elements[...], got Bs). Replaced with the convention nn.Linear.forward actually uses:
a type parameter bound to IntTuple, spliced into the shape list with
*Elements[...] (def forward[Bs: IntTuple](..., x: Tensor[[*Elements[Bs], D]])).

tensor-shapes-setup.mdx is intentionally not touched here — it's already
being fixed by #4559.

Two things came up during this pass that are real but out of scope for this
issue, noted here rather than silently fixed:

• tensor-shapes-tutorial-advanced.mdx's DCGAN section claims
  DCGAN.ngf * 8 resolves to Literal[512]; it actually widens to plain
  int. Unrelated to the shape-syntax bug — a separate literal-arithmetic
  question.
• The recursive/exponential examples in tensor-shapes-tutorial-architectures.mdx
  (UNet.recurse/_decode, Generator._chain) hit genuine algebraic-gap
  solver limitations even with the corrected syntax — the same class of gap
  the page's own "Algebraic gaps" section already documents and prescribes
  type: ignore for.

Fixes #4560

Test Plan

Environment: pyrefly==1.2.0 and pyrefly-torch-stubs==1.2.0 from PyPI in a
clean venv, matching the issue's own reproduction environment.

Confirmed the single-file default preset (pyrefly check file.py with no
pyrefly.toml) silently uses the lenient basic preset, which disables
assignment/call-shape validation and would falsely show 0 errors even on
broken code — all checks below use pyrefly check -p default to get real
validation.

Re-ran both of the issue's own reproductions, extracted verbatim from the
now-fixed files:

• The BaselineActor example from tensor-shapes-tutorial-basics.mdx.
  (the one that produced the issue's 8 errors) — now 0 errors.
• The Attention/Int[X] | None example from tensor-shapes-reference.mdx
  (Expected 1 type argument for Tensor, got 3) — that error is gone; the
  only remaining diagnostic is an unrelated missing-return from the
  fragment's own ... placeholder body, present in the original doc too.

For every other changed code block, reconstructed it with minimal synthetic
scaffolding (stand-in modules for fragments that reference outer context)
and ran pyrefly check -p default, confirming assert_type calls pass and
signatures unify. Swept all 7 files afterward for any remaining flat
Tensor[...] form — none found.

Did not run the Docusaurus build (website/'s node_modules isn't
installed in this environment); checked code-fence and bracket balance
across all 7 files as a structural proxy instead.

AI usage disclosure

Per the AI Usage section of CONTRIBUTING.md: this fix, its verification
against the shipped stubs, and this description were produced by an AI
agent (Claude Code) working in my checkout. I reviewed them before
submitting.

[meta-cla]

Hi @Vishwaspatel2401!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[ting-hong-shieh]

I filed #4560, so I ran your branch against the stubs to check the examples. Environment: pyrefly 1.2.0 and pyrefly-torch-stubs 1.2.0 from PyPI, Python 3.12, Linux.

Checks clean:

• the Attention example on the reference page
• the variadic form you introduced — [Bs: IntTuple] with Tensor[[*Elements[Bs], D]]
• the four rows of the shape-form table, and the .shape / .size(0) claims below them
• the three exposition examples on tensor-shapes.mdx (Linear, custom_rand_tensor, mm)
• the basics tutorial, reassembled into a full BaselineActor the way the page builds it up — all three assert_type calls hold

Your mm signature also matches the real stub's shape relation (the stub names the parameters [N, K, M] where you have [M, K, N], but the relation is the same).

One thing I think is worth fixing: the new names have no stated origin.

After this change, five pages use IntVar, IntTuple, and Elements, but none of them say where those come from. The reference page's only sourcing is line 26, which covers Int alone. Copying the variadic snippet as printed gives:

ERROR Could not find name `IntTuple` [unknown-name]
ERROR Could not find name `Elements` [unknown-name]

This isn't a regression you introduced by accident so much as a side effect of the correct fix: the old spellings needed no import, since *Bs is native PEP 646 syntax and unbounded [D] needs nothing. The new ones do. Extending that line 26 sentence to cover all four names, or adding an import line to the snippets, would close it.

Two smaller notes, take or leave:

In the concepts section of tensor-shapes.mdx, "takes Tensor[[*Elements[Bs], 3]] as input" introduces Bs with no antecedent — it's the first mention on the page, and the variadic mechanism isn't explained until the reference page. The old Tensor[..., 3] read more naturally in prose even though it wasn't a real annotation.

The two heading renames change their anchors (#tensord1-d2-, #variadic-dimensions-with-bs). Nothing in the repo links to either, so no internal breakage — just noting it for external links. The old headings were wrong, so renaming them looks right to me.

Scope: I didn't reassemble every incremental fragment on all seven pages. The architectures, advanced, and loops examples I only checked structurally, not by running them.

Disclosure, per the AI Usage section of CONTRIBUTING.md: these checks and this comment were produced by an AI agent (Claude Code) working in my checkout. I reviewed them before posting.

[Vishwaspatel2401]

Thanks for running the branch against the stubs — good catch on the missing sourcing.

Fixed the import gap: extended the reference page's existing Int[X] sentence to also cover IntVar, IntTuple, and Elements, so there's one place that says where all four names come from. Didn't add per-snippet import lines since that would break from how every other fragment on these pages is shown (none of them show imports, including Int before this change) — the reference page's sourcing sentence is the one place meant to answer that question, so extending it felt like the right fix rather than adding inconsistent per-snippet imports.

Also fixed the Bs-with-no-antecedent issue on tensor-shapes.mdx — rewrote that sentence in plain words instead of using the Elements[Bs] syntax before it's ever explained, and linked to the reference page's variadic section for the actual syntax.

Agreed on the anchor renames — confirmed the same thing, nothing in the repo links to either old anchor, so leaving the new headings as-is.

Pushed as a follow-up commit on the same branch.

[meta-codesync]

This pull request has been imported. If you are a Meta employee, you can view this in D116250396. (Because this pull request was imported automatically, there will not be any future comments.)