[chesterxgchen]

Fixes #5539.

Description

Reorganize tutorial navigation so readers can distinguish getting started, learning one feature, finding a runnable example, and following a structured course. This is Step 3 of the documentation redesign and separates tutorial ownership from the README and Quick Start work in #5328.

During review, the scope was expanded to audit and refresh the notebooks in this same PR. Accurate navigation needs to lead to instructions that match the implementation, not just reorganize stale links.

Navigation and ownership

• docs/tutorials.rst owns learning-path navigation. Lead with Quick Start and Hello World, then offer focused feature tutorials, the example catalog, and structured training. Group notebooks by outcome: build/test, operate/deploy, and observe/troubleshoot.
• examples/tutorials/README.md owns the detailed notebook index. Record each notebook's purpose, prerequisites, completion signal, owning subsystem, and dated verification context. Keep runnable instructions in the notebooks and example READMEs.
• Correct the onboarding claims. Hello World examples have different dependencies, asset preparation, and command-line arguments; neither entry point promises a universal bare python job.py. Development-checkout verification is not presented as released-version verification.
• Keep versioned training distinct. Identify the self-paced course as the NVFLARE 2.6 edition, retain its 100+ notebooks and 80 videos description, and explain that NVIDIA DLI courses are versioned independently.
• Preserve compatibility. Keep the filenames, URLs, orphan status, and existing reference label of docs/examples_tutorials.rst and docs/examples/tutorial_notebooks.rst as compatibility pointers. No notebook is removed or renamed.

Notebook audit and fixes

Audited all six feature notebooks against current source and the 2.9 release history. Five needed changes; nvflare_cli.ipynb was checked and remains unchanged.

• Job Recipe: remove the outdated technical-preview label; explicitly use the maintained Hello PyTorch model/client and synthetic data; avoid the tutorial directory's old modules shadowing that example during export and execution; correct the dictionary-model arguments; connect the optional production section to the startup kit it actually provisions. Explain optional checkpoint and production prerequisites.
• FLARE API: export the example with the notebook kernel's Python and check failures; submit the exported job by its actual path; replace deprecated cloning with resubmission; correct abort/delete return-value descriptions; retry only the job-specific startup-abort response within a 30-second window; monitor before deletion and close the session.
• POC: use current workspace-configuration commands, clarify that the optional tree utility is an OS package, and separate optional Docker/HE setup from the basic flow.
• Logging and simulator: repair moved documentation links and fix the custom-logger example's API and class initialization.
• Regression tests: check notebook documentation targets, Recipe source/export and production paths, FLARE API submission/cleanup and bounded startup-abort retries, and the custom-logger example.

The PR now changes four documentation pages, five notebooks, and one test file. It does not change NVFLARE runtime implementation or package dependencies.

Coordination with #5328

Commit d4a2b6c12 removes the overlapping tutorial-page edits from #5328. That PR retains the root README, Quick Start, and overview figure; this PR owns tutorial navigation and the reviewed notebook refresh.

Types of changes

• Non-breaking change (fix or new feature that would not break existing functionality).
• New tests added to cover the changes.
• Documentation updated.

Testing

Review-time checks on macOS, Python 3.13.15, using this PR's development checkout based on b329c8113:

• python -m pytest -q tests/unit_test/examples/tutorial_notebooks_test.py tests/unit_test/examples/poc_tutorial_commands_test.py tests/unit_test/examples/recipe_export_arguments_test.py tests/unit_test/examples/hello_pt_client_test.py — 44 passed after the startup-abort follow-up.
• ./runtest.sh -s --skip-install — Black, isort, flake8, and Agent Skills lint passed using the existing development environment. Black skips notebooks in this environment; notebook syntax was checked separately.
• All six notebooks passed nbformat schema validation; 77 code cells compiled after IPython transformation; 46 runnable CLI invocations parsed against the current CLI. Parsing does not execute those commands.
• Revised Job Recipe cells ran two clients, three rounds in both simulation and native POC mode: FINISHED:COMPLETED.
• hello-numpy simulations with default and custom JSON logging completed successfully.
• At 59d709f43, all 13 FLARE API code cells executed against a temporary two-client POC deployment, substituting only its admin-kit location: connect, export, submit, monitor, download, resubmit, abort, delete, and close. The first NumPy job completed; the second was aborted and both were deleted.
• python examples/tutorials/nvflare_cli_job.py --job-dir <temporary-directory> --num_rounds 2 — job export passed.
• SKIP_API_DOCS=1 sphinx-build -q -b html docs <temporary-directory> — HTML build succeeded with warnings elsewhere in the checkout; no warnings named the changed documentation pages. Used Sphinx directly to avoid reinstalling dependencies or cleaning existing artifacts.
• Relative notebook links and RST references checked; git diff --check passed. Fresh-context review of the final diff reported no remaining findings.

Startup-abort follow-up: four regression cases failed on 59d709f43 and pass with the fix. Tests exercise the real Session.abort_job() response-to-exception mapping with mocked transport and time, including retry success, a job that completes during retry, deadline exhaustion, other-job responses, unrelated errors, and authorization failures. The full notebook mock-session test verifies that monitoring, deletion, and session closure still follow a successful retry. python -m pytest -q tests/unit_test/private/fed/server/job_runner_abort_test.py tests/unit_test/integration_test/action_handlers_test.py also passed (63 tests). Style and notebook schema/syntax checks were rerun. The final retry-only change was not rerun against a live deployment; the earlier live run aborted before startup and did not exercise this race.

Rebase and HE-install correction: rebased onto upstream/main at a0a35019b without conflicts; git range-diff confirmed that all four existing commit patches were preserved. Restored %pip install "nvflare[HE]" in the POC notebook so TenSEAL versions follow NVFLARE's HE-extra dependency constraints while installation uses the notebook kernel. After rebasing, reran the six test modules listed above together (107 passed), ./runtest.sh -s --skip-install, notebook schema/syntax/CLI parsing checks, and git diff --check; all passed. The HE install itself, live deployments, and HTML build were not rerun for this correction.

The README preserves the earlier Linux/Python 3.14 authoring record separately from these review-time checks. Not run: every POC/CLI notebook cell, optional Docker/HE/checkpoint-loading/production deployment sections, execution against released wheels, the full runtime test suite, and API-reference generation. The release comparison was a source audit, not a released-wheel compatibility certification.

Risk

Low, scoped to tutorial navigation and executable teaching examples. Likely failure modes are inaccurate prerequisites, broken links, or example path/import differences across environments. Existing page URLs and labels are preserved; targeted tests and live simulator/POC runs cover the corrected core paths. Optional deployment sections retain environment-specific prerequisites and were not executed. No runtime API, persisted format, or package dependency changes.

How to revert

Revert this PR's documentation, notebook, and test changes. There are no runtime or saved-state migrations. Reverting does not restore the tutorial edits removed from #5328; those would need to be reapplied separately if desired.

[greptile-apps]

Confidence Score: 5/5

[Low impact] This PR appears safe to merge; no new actionable issues remain.

Summary

This PR separates onboarding, feature tutorials, runnable examples, and structured training. It also refreshes five notebooks and adds focused regression tests.

• Tutorial pages now guide readers from a first run to focused training.
• The Job Recipe tutorial runs the maintained Hello PyTorch example.
• The FLARE API tutorial exports and manages repeat job runs locally.
• The POC tutorial uses current workspace commands and optional setup.
• Logging and simulator notebooks point to current guides and runnable logger code.

_{Reviews (4) · Last reviewed commit: "Restore the NVFLARE HE extra in the POC ..." · Reviewed by Greptile}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.65%. Comparing base (a0a3501) to head (0bfce37).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5540   +/-   ##
=======================================
  Coverage   71.65%   71.65%           
=======================================
  Files        1048     1048           
  Lines      112323   112323           
=======================================
  Hits        80480    80480           
  Misses      31843    31843           

Flag	Coverage Δ
unit-tests	71.65% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.