Add console-script entry points for the main drivers

[DLWoodruff]

What

Adds console-script entry points so users who pip install mpi-sppy (or pip install -e . from a clone) can run the main drivers as commands on their PATH, without having to locate the files in site-packages:

Command	Equivalent to
mpi-sppy-generic-cylinders	python -m mpisppy.generic_cylinders
mpi-sppy-mrp-generic	python -m mpisppy.mrp_generic
mpi-sppy-one-sided-test	python -m mpi4py mpi_one_sided_test.py

Changes

• pyproject.toml: add [project.scripts] and an explicit [tool.setuptools] package/module declaration. The package list matches the previous find_packages() result exactly (verified by building a wheel) and additionally installs the top-level mpi_one_sided_test.py so its console script can import it.
• mpisppy/generic_cylinders.py, mpisppy/mrp_generic.py: move the __main__ body into a main() callable so the entry points have a target. The __main__ guard still calls main(), so the existing runpy-based __main__ tests (test_generic_cylinders.py, test_mrp_generic.py) continue to exercise the refactored code.
• Docs / README: advertise the console scripts as the standard, location-independent invocation. Because pip install -e . also creates them, there is no pip-vs-source distinction to document.

Notes

• For multi-rank parallel runs, the python -m mpi4py module form is still recommended (e.g. mpiexec -np 3 python -m mpi4py -m mpisppy.generic_cylinders ...) so that mpi4py installs its abort-on-exception handler. The docs keep that guidance.
• Command names are prefixed with mpi-sppy- to avoid putting generic names like generic_cylinders on users' PATH.

Testing

• Built a wheel and confirmed all three scripts appear in entry_points.txt and that every mpisppy subpackage is still packaged.
• pip install -e . regenerates the three launchers on PATH; each runs.
• Docs build clean (cd doc && make html), with no warnings on the edited pages.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.18%. Comparing base (a105686) to head (58e4e0f).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #803   +/-   ##
=======================================
  Coverage   76.18%   76.18%           
=======================================
  Files         169      169           
  Lines       22263    22267    +4     
=======================================
+ Hits        16961    16965    +4     
  Misses       5302     5302           

☔ 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.

[Copilot]

Pull request overview

This PR adds console_scripts entry points so the primary mpi-sppy drivers can be invoked as stable commands after installation, and refactors the existing module __main__ bodies to provide main() callables as entry-point targets. It also updates README/docs to promote the new location-independent invocation while preserving guidance for multi-rank MPI runs.

Changes:

• Add [project.scripts] entry points (and explicit setuptools package/module configuration) in pyproject.toml.
• Refactor mpisppy.generic_cylinders and mpisppy.mrp_generic to expose main() and keep python -m ... behavior.
• Update README and Sphinx docs to advertise the new CLI commands and adjust MPI one-sided test invocation.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Documents the new console scripts and updates the one-sided MPI test invocation.
pyproject.toml	Defines console-script entry points and explicitly declares packages/py-modules for setuptools.
mpisppy/mrp_generic.py	Refactors the module entry point into a main() callable for console-script support.
mpisppy/generic_cylinders.py	Refactors the module entry point into a main() callable for console-script support.
mpi_one_sided_test.py	Updates the suggested invocation message to use the new console script.
doc/src/seqsamp.rst	Adds a note about the mpi-sppy-mrp-generic console script and MPI runner guidance.
doc/src/quick_start.rst	Updates the MPI verification step to use the console script.
doc/src/install_mpi.rst	Updates MPI install-test instructions to use the console script.
doc/src/generic_cylinders.rst	Adds a note about the mpi-sppy-generic-cylinders console script and MPI runner guidance.

Comments suppressed due to low confidence (1)

mpisppy/mrp_generic.py:81

• The no-args usage message only mentions the python -m mpisppy.mrp_generic ... form, but this PR adds a console script entry point. Updating the usage text to include mpi-sppy-mrp-generic will make the CLI guidance match the documented/packaged entry points.

def main():
    if len(sys.argv) == 1:
        print("The python model file module name (no .py) must be given.")
        print("usage, e.g.: python -m mpisppy.mrp_generic --module-name farmer"
              " --num-scens 3 --solver-name cplex --stopping-criterion BM")
        quit()

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bknueven]

It makes sense you can do this -- I wonder if we should update the documentation and examples to do so. I'd think this would be the preferred way of running so you don't need to even know where mpi-sppy is installed.

Or, I wonder if we could create our own script (a little harder than entry points) which effectively did python -m mpi4py -m mpisppy.generic_cylinders for the user ... beyond the scope of this PR, for sure.