Recommend installing optional dependencies for examples in the actual scripts

[charlesbmi]

Changes

Document the extra dependencies to run examples.

Behavior

Documentation-only change. Docs should still build.

Review checklist

• All existing tests and checks pass
• Unit tests covering the new feature or bugfix have been added
• The documentation has been updated if necessary

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Docs Rendering Validate that the inserted reStructuredText note block inside Python comments is actually rendered as intended by the documentation tooling used for examples (e.g., Sphinx-Gallery / myst / nbconvert). If the tool expects a specific marker/header format, this directive may otherwise show up as plain comments or be skipped. # %% # .. note:: # To run this example, we recommend installing mach with all optional dependencies: # # .. code-block:: bash # # pip install mach-beamform[all] # # This ensures all dependencies for the examples are available. Consistency Ensure the installation guidance is consistent with the actual project/package naming and extras configuration. The text says “installing mach with all optional dependencies” but the command uses mach-beamform[all]; confirm this is the correct extra and that “mach” vs mach-beamform is not confusing or incorrect for users. # %% # .. note:: # To run this example, we recommend installing mach with all optional dependencies: # # .. code-block:: bash # # pip install mach-beamform[all] # # This ensures all dependencies for the examples are available. Install Guidance Confirm the recommended install command and explanation match how extras are defined and distributed (e.g., whether [all] exists, whether it pulls GPU/CUDA deps appropriately, and whether there should be a CPU-only option). Also ensure this guidance aligns with any top-level installation docs to avoid conflicting instructions. **Recommended Installation:** To run all examples without dependency issues, we recommend installing mach with all optional dependencies:: pip install mach-beamform[all] This includes all visualization, data loading, and example-specific dependencies.

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Centralize dependency instructions in README Remove the redundant dependency installation instructions from individual example scripts. Instead, centralize this information exclusively in the examples/README.rst file to create a single source of truth and simplify future updates. Examples: examples/doppler.py [33-41] # %% # .. note:: # To run this example, we recommend installing mach with all optional dependencies: # # .. code-block:: bash # # pip install mach-beamform[all] # # This ensures all dependencies for the examples are available. examples/plane_wave_compound.py [22-30] # %% # .. note:: # To run this example, we recommend installing mach with all optional dependencies: # # .. code-block:: bash # # pip install mach-beamform[all] # # This ensures all dependencies for the examples are available. Solution Walkthrough: Before: # In examples/README.rst ... **Recommended Installation:** pip install mach-beamform[all] ... # In examples/doppler.py and other examples """Docstring""" # %% # .. note:: # To run this example, install with all optional dependencies: # # pip install mach-beamform[all] # # %% # Import Required Libraries ... After: # In examples/README.rst ... **Recommended Installation:** pip install mach-beamform[all] This includes all visualization, data loading, and example-specific dependencies. ... # In examples/doppler.py and other examples """Docstring""" # %% # Import Required Libraries ... Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies redundant documentation added in the PR and proposes centralizing it, which improves long-term maintainability and provides a single source of truth.	Low
General	Quote package name for shell compatibility To ensure shell compatibility, enclose the package name and its extras in quotes in the pip install command, for example, pip install "mach-beamform[all]". examples/README.rst [23] -pip install mach-beamform[all] +pip install "mach-beamform[all]" Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies a potential shell compatibility issue and provides a robust fix by quoting the package name, improving the reliability of the installation instructions for users of shells like zsh.	Low
	Render note as Markdown cell Convert the commented note into a Jupyter Markdown cell by changing # %% to # %% [markdown] and removing the comment prefixes for proper rendering. examples/doppler.py [33-41] -# %% -# .. note:: -# To run this example, we recommend installing mach with all optional dependencies: -# -# .. code-block:: bash -# -# pip install mach-beamform[all] -# -# This ensures all dependencies for the examples are available. +# %% [markdown] +.. note:: + To run this example, we recommend installing mach with all optional dependencies: + ```bash + pip install mach-beamform[all] + ``` + + This ensures all dependencies for the examples are available. + [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 5 __ Why: This is a good suggestion that improves the presentation of the example file when viewed in a notebook environment, making the instructions clearer and more readable.	Low
More