docs: refine Tutorial hierarchy and compiler guides

[poilsosart]

Summary

• Reorganize the Tutorial hierarchy around building neural networks for online learning.
• Rename foundational sections to clarify the progression from operators to hidden-state management and neural-network layers.
• Distinguish custom ETP primitive development from primitive-transform customization.
• Improve the compiler and runtime tutorials with executable ETraceGraph and CompilationReport inspection examples.
• Add links from foundational tutorials to the API Reference.
• Standardize algorithm naming as pp-prop.
• Keep Graph Compilation and Visualization text/code based without custom figures, CSS, JavaScript, or static API assets.

Validation

• Re-executed graph_compilation.ipynb and visualization.ipynb with the project virtual environment.
• Built the documentation with warnings treated as errors:

sphinx-build -b html -E -a -W --keep-going docs docs/_build/html

• Confirmed git diff --check passes.
• Confirmed no new Python, CSS, JavaScript, standalone JSON, spec, or static figure files are included.

Summary by Sourcery

Refine online-learning documentation by clarifying the progression from ETP operators through neural-network layers to hidden-state management, and by enriching compiler/graph tutorials with executable inspection examples.

Documentation:

• Rename and reposition foundational tutorials to emphasize operators, neural-network layers, and hidden states in the online-learning workflow.
• Clarify BrainTrace compiler concepts by documenting hidden-state discovery, HiddenGroup usage, and linking to the Compiler and Executor API reference.
• Update ETP operator, neural-network layer, and custom primitive tutorials with cross-references that distinguish primitive creation from parameter-transform customization.
• Standardize algorithm terminology around the pp-prop estimator and update SNN and advanced algorithm docs accordingly.
• Enhance graph compilation and visualization notebooks with runnable examples that show ETraceGraph structure, CompilationReport contents, and exclusion diagnostics without adding custom visual assets.

[sourcery-ai]

Reviewer's Guide

Refines tutorial hierarchy and wording around online-learning concepts, strengthens links to API references, and makes the Graph Compilation and Visualization notebooks fully executable, showing how to inspect ETraceGraph and CompilationReport programmatically while standardizing algorithm naming to pp-prop.

Sequence diagram for compiling a model and inspecting ETraceGraph and CompilationReport

sequenceDiagram
    actor User
    participant braintrace
    participant Learner
    participant CompilationReport
    participant ETraceGraph

    User->>braintrace: compile(model, algo, x0, batch_size)
    braintrace-->>Learner: return Learner
    Learner-->>ETraceGraph: graph
    Learner-->>CompilationReport: report

    User->>Learner: show_graph()
    Learner->>ETraceGraph: render hidden_groups and relations

    User->>CompilationReport: report.show(level)
    CompilationReport-->>User: counts, etrace_weights, excluded_weights, diagnostics

    User->>ETraceGraph: inspect hidden_groups, hidden_param_op_relations
    ETraceGraph-->>User: hidden_paths, primitive, hidden_groups

Loading

File-Level Changes

Change	Details	Files
Visualization tutorial notebook now includes executed examples that print ETraceGraph and CompilationReport details for single-layer, two-layer, and convolutional RNNs.	Re-ran all cells and stored execution counts, timestamps, stdout, and stderr in visualization.ipynb. Extended SingleLayerRNN example to show compiler warnings and learner.report usage with counts and included/excluded weights. Added programmatic inspection of learner.graph, including hidden_groups, hidden_param_op_relations, and perturbation presence. Expanded TwoLayerRNN example to show hidden group separation, per-weight relations, exclusion reasons, and CompilationReport counts. Added ConvRNN example demonstrating an ETP-traced convolutional kernel and non-temporal readout weight. Clarified summary text on using learner.report and ETraceGraph for validation and visualization limitations.	docs/tutorials/visualization.ipynb
Graph Compilation tutorial notebook now mirrors the Visualization examples with executed outputs and clarified guidance on compile_etrace_graph usage and summary.	Re-ran all cells and persisted execution metadata and stdout in graph_compilation.ipynb. Extended SingleLayerRNN example output to include compiler warnings and non-temporal parameter classification. Clarified narrative around compile_etrace_graph as an advanced inspection tool distinct from braintrace.compile. Adjusted final summary to point to visualization.ipynb for further inspection of compiled graphs.	docs/tutorials/graph_compilation.ipynb
Hidden state tutorial is reframed around online learning, with clearer explanations of compiler APIs, grouping, and linkage between hidden state and ETP-marked parameters plus API reference links.	Retitled tutorial from Hidden State Management to Hidden States for Online Learning and updated introduction to tie operators, layers, and hidden states together. Rewrote compiler-discovery steps to reference extract_module_info, ModuleInfo, and HiddenGroup, with explicit API links. Clarified Jacobian and gradient discussion to reference braintrace.compile and CompilationReport, and emphasize ETP-marked parameter operations. Updated summary to emphasize brainstate containers, automatic discovery, grouping, operation-based selection, flexible initialization, and related APIs. Added pointers to Compiler and Executor API and discovery functions like find_hidden_groups_from_module.	docs/tutorials/hidden_states.ipynb
Neural network layers tutorial now presents braintrace.nn as layers for online learning, emphasizes operation-based selection, references API docs, and updates layer family table to use explicit Sphinx roles.	Retitled tutorial to Neural Network Layers for Online Learning and rewrote overview to describe composing ETP operations into recurrent blocks. Clarified that selection is operation-based with func and class references (braintrace.matmul, braintrace.nn.Linear, brainstate.nn.Linear). Updated layer family table to reference specific braintrace.nn classes via Sphinx roles and link to their underlying ETP operations. Clarified guidance on importing activation, normalization, and pooling from brainstate.nn and deprecated compatibility forwarding. Updated next-steps section to point to Hidden States for Online Learning, Graph Compilation, and the Neural Network Layers API.	docs/tutorials/neural_network_layers.ipynb
ETP operator tutorial is reframed as Operators for Online Learning, with clearer positioning of the five primitives, API links, and next-step navigation.	Retitled tutorial to Operators for Online Learning and adjusted introduction to focus on marking parameterized computations for the compiler. Updated function reference table to use Sphinx func roles and mention the ETP Operators API as authoritative reference. Adjusted next-steps section to link to Neural Network Layers for Online Learning, Hidden States for Online Learning, and Creating Custom ETP Primitives. Ensured terminology consistently uses operators instead of primitives where appropriate in the user-facing docs.	docs/tutorials/five_primitive_functions.ipynb
Advanced ETP primitives tutorial is reframed around primitive creation, distinguishing it from transform customization and linking to the operators tutorial.	Retitled tutorial to Creating Custom ETP Primitives and rewrote introduction to emphasize the primitive registration contract. Clarified scope as primitive creation and registration, and pointed to a separate transforms tutorial for altering existing operators. Updated section headings and summary to use "Creating" rather than "Adding" primitives and to mention follow-on transforms tutorial. Linked back to Operators for Online Learning for context on public operators.	docs/advanced/etp_primitives.ipynb
Advanced primitive-transform customization tutorial is retitled and reworded to focus on parameter transforms for existing operators and their chain-rule invariants.	Retitled tutorial to Customizing Parameter Transforms for ETP Operators and rewrote introduction to clarify scope (existing operators, not registration). Updated cross-references to Creating Custom ETP Primitives as the prerequisite chapter. Clarified that the chapter covers weight_fn, kernel_fn, factor hooks, exact chain-rule propagation, and fast-path gating. Adjusted later headings to reflect transform-hook semantics for registered primitives instead of primitive creation.	docs/advanced/customizing_primitive_transforms.ipynb
Custom algorithm development tutorial is slightly retitled and clarified while standardizing naming of pp-prop and hierarchy description.	Retitled section header to Developing Custom Algorithms while preserving overall content. Ensured algorithm hierarchy description consistently refers to pp_prop and ES_D_RTRL/IODimVjpAlgorithm relationship. Kept emphasis on shared graph compilation infrastructure and clarified example customizations (trace clipping, Jacobian normalization).	docs/advanced/custom_algorithms.ipynb
SNN online learning tutorial is updated to use pp-prop naming consistently and clarify algorithm parameterization and comparison table.	Changed tagline to "Train a spiking neural network using pp-prop" and removed ES-D-RTRL from primary phrasing. Updated learning objective to reference braintrace.pp_prop only. Retitled training section to "Training with pp-prop" and clarified that pp_prop is backed by IODimVjpAlgorithm. Updated comparison table to describe D-RTRL vs pp-prop without historical ES-D-RTRL naming. Clarified decay_or_rank semantics as part of pp-prop configuration.	docs/tutorials/snn_online_learning.ipynb
Quickstart concepts notebook and other cross-links are updated to use new tutorial titles and standardized operator terminology.	Updated quickstart concepts links to Operators for Online Learning and Creating Custom ETP Primitives. Adjusted references throughout to the new Hidden States for Online Learning and Neural Network Layers for Online Learning titles. Removed or updated mentions of ETP Operator Fundamentals to the new operator tutorial name. Kept the Graph Compilation and other advanced tutorials referenced as before but with refreshed titles.	docs/quickstart/concepts.ipynb docs/tutorials/snn_online_learning.ipynb docs/tutorials/five_primitive_functions.ipynb docs/advanced/etp_primitives.ipynb

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• In the learner.report example for the single-layer RNN, etrace_weights shows the same weight path twice; consider either explaining that this reflects separate trainable keys (e.g., weight/bias) or adjusting the example to avoid confusion for readers expecting unique weight entries.
• Several notebook outputs now embed local file-system paths in warnings (e.g., D:\BrainTrace\.venv\...); it may be worth re-running or lightly editing those cells to avoid publishing environment-specific paths in the documentation.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the `learner.report` example for the single-layer RNN, `etrace_weights` shows the same weight path twice; consider either explaining that this reflects separate trainable keys (e.g., weight/bias) or adjusting the example to avoid confusion for readers expecting unique weight entries.
- Several notebook outputs now embed local file-system paths in warnings (e.g., `D:\BrainTrace\.venv\...`); it may be worth re-running or lightly editing those cells to avoid publishing environment-specific paths in the documentation.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!