docs: render one page per public symbol via autosummary toctree

[adityasingh2400]

Fixes #1320.

The API reference currently renders every function and class of a module on a single page. The optimizers and transformations pages are the clearest examples: each lists dozens of symbols, all fully expanded inline. That makes the pages very long and, as noted in the issue, an in-page Ctrl+F search spills over into unrelated symbols.

This is the same restructuring the JAX docs use: add :toctree: generated/ to the .. autosummary:: blocks and set autosummary_generate = True, so Sphinx emits a dedicated page per public symbol. The summary tables stay as the per-page index and now link out to each symbol's page, and the curated section grouping on each page (for example the "Numerical Stability" / "Linear Algebra Operators" groups in the utilities page) is preserved. The redundant per-symbol autofunction/autoclass directives are removed since the generated pages cover them.

Two small templates under docs/_templates/autosummary keep the per-symbol pages consistent with the current rendering: a plain .. autoclass:: for classes (so the existing autodoc_default_options still govern member display) and the matching auto* directive for everything else.

The set of documented symbols is unchanged. I checked that the qualified names declared across the API pages are identical before and after (318 symbols), so nothing is dropped or added, the symbols just live on individual pages now.

Generated stubs are build artifacts, so docs/api/generated is added to .gitignore alongside the other generated documentation directories.

While restructuring, two pre-existing problems showed up in the build and are fixed here:

• contrib.rst referenced optax.contrib.GaloreState, but the exported name is GaLoreState. The old entry failed to import during the autosummary build.
• A few :doc: references to the examples gallery used relative paths (../_collections/...). Relative :doc: targets resolve from the page they render on, so they broke once the symbols moved onto their own pages one directory deeper. They are now absolute (/_collections/...), which resolves from any page (including the current ones).

Testing: make html and make doctest both pass locally (699 doctests, 0 failures). I compared the build warnings before and after: the change introduces no new warnings and removes the GaloreState import failure and a duplicate optax.masked object-description warning.

[adityasingh2400]

The pyrefly check failure here looks unrelated to this PR. This change only touches documentation: the docs/api/*.rst autosummary pages, docs/conf.py, and a few :doc: link paths in docstrings. None of the files pyrefly flags (optax/transforms/_monitoring.py, optax/transforms/_masking_test.py, optax/tree_utils/_random.py, optax/tree_utils/_state_utils.py, optax/tree_utils/_state_utils_test.py) are modified by this PR.

I reproduced "python3 -m pyrefly check optax" locally on a clean main checkout and on this branch. Both report the identical 601 errors with 637 suppressed, and the exact error lines diff to zero. So the failure is pre-existing on main, from the recent pytype to pyrefly migration, and this PR neither causes nor worsens it.

Could a maintainer confirm and rerun the job, or advise if you would prefer I address the pre-existing pyrefly errors separately? I would rather not mix unrelated type fixes into a docs PR.

[adityasingh2400]

The pyrefly check is failing on optax/tree_utils/_random.py:84 and optax/tree_utils/_state_utils.py:498 and :502, which this PR does not modify. These same errors reproduce on a clean checkout of upstream main (the scheduled CI run on main from today, run 26432289464, shows the same failure). The PR branch is already based on the latest upstream commit fe6dbd3, so the pyrefly failures are pre-existing on main rather than introduced here.

[rdyro]

Thanks for this PR, yes we're in the middle of a migration to pyrefly, so the CI failures are unrelated.

I'll need some time to review this, but thanks for contributing!

[adityasingh2400]

Thanks, no rush. That matches what I saw, the pyrefly errors are all in unrelated files from the in-progress migration, so this docs change does not touch them. Appreciate you taking a look when you get a chance.