misc cleanup: skip flaky test_values, fix dup-doc warning, ignore artifacts (#688)

Three small loose ends bundled into one PR.

* mpisppy/tests/test_admmWrapper.py, mpisppy/tests/test_stoch_admmWrapper.py:
  test_values in both files fails when run via pytest's subprocess
  capture (returncode=1, empty stdout AND stderr) but works
  identically when launched from a bare Python script or shell.  The
  subprocess seems to die before producing any output — likely a
  pytest stdio-capture / file-descriptor interaction with Open MPI's
  I/O forwarding.  Mark both tests with @unittest.skip and a clear
  reason pointing at the example bash scripts as the manual
  workaround until the root cause is diagnosed.

* doc/src/generic_admm.rst: the file documents consensus_vars_creator
  twice (once for --admm, once for --stoch-admm), which produced a
  Sphinx "duplicate object description" warning.  Add :no-index: to
  the --stoch-admm directive so only one ends up in the index.

* .gitignore: add conservative patterns for mpi-sppy runtime
  artifacts that have been accumulating untracked in many users'
  working trees — per-rank iteration summaries, _delme*/delete_me*
  scratch dirs, specific.csv_* exports, example output files
  (ef.txt, hub.log, solution_*.txt, *_full_solution/, *_pickles/,
  *_cyl_nonants.npy).  Leaves ambiguous patterns (e.g., archive/,
  CI/, *.perf.csv) untouched.

Tests: 42 passed, 2 skipped (the two test_values).  Doc build:
4 warnings -> 3 warnings (dup-description warning gone).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DLWoodruff

.gitignore

@@ -137,3 +137,23 @@ dmypy.json
 
 # .DS_Store
 .DS_Store
+
+# mpi-sppy runtime artifacts from running examples/tests.  Conservative
+# patterns — only obvious per-run output, not anything that could be a
+# fixture.  Add more here as new artifact patterns appear.
+*_summary_iter*_rank*.txt
+None_summary_*.txt
+__*___summary_*.txt
+_delme*
+delete_me*
+specific.csv_*
+_temp_*.csv
+
+# Example output files (each example regenerates these on every run)
+examples/**/ef.txt
+examples/**/hub.log
+examples/**/xhateval.log
+examples/**/solution_*.txt
+examples/**/*_full_solution/
+examples/**/*_pickles/
+examples/**/*_cyl_nonants.npy

doc/src/generic_admm.rst

@@ -173,6 +173,7 @@ Additional functions for ``--stoch-admm``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. py:function:: consensus_vars_creator(admm_subproblem_names, stoch_scenario_name, **scenario_creator_kwargs)
+   :no-index:
 
    Creates the consensus variables dictionary for stochastic ADMM.
 

mpisppy/tests/test_admmWrapper.py

@@ -129,6 +129,14 @@ def _extracting_output(self, line):
             raise RuntimeError("Cannot find outer and inner bounds in pattern"
                                f" in this output {line=}")
 
+    @unittest.skip(
+        "mpiexec subprocesses die silently (returncode=1, empty stdout/stderr) "
+        "when launched via subprocess.run from inside pytest, but the exact "
+        "same command works when run from a bare Python script or a shell. "
+        "Likely a pytest stdio-capture / file-descriptor interaction with "
+        "Open MPI's I/O forwarding.  Run manually via examples/distr/go.bash "
+        "to exercise this path until the root cause is diagnosed."
+    )
     def test_values(self):
         command_line_pairs = [(f"mpiexec -np 3 python -u {python_args} -m mpi4py distr_admm_cylinders.py --num-scens 3 --default-rho 10 --solver-name {solver_name} --max-iterations 50 --xhatxbar --lagrangian --rel-gap 0.01 --ensure-xhat-feas" \
                          , f"python {python_args} distr_ef.py --solver-name {solver_name} --num-scens 3 --ensure-xhat-feas"), \

mpisppy/tests/test_stoch_admmWrapper.py

@@ -129,6 +129,15 @@ def _extracting_output(self, line):
             raise RuntimeError("The test is probably not correctly adapted: can't match the format of the line")
 
 
+    @unittest.skip(
+        "mpiexec subprocesses die silently (returncode=1, empty stdout/stderr) "
+        "when launched via subprocess.run from inside pytest, but the exact "
+        "same command works when run from a bare Python script or a shell. "
+        "Likely a pytest stdio-capture / file-descriptor interaction with "
+        "Open MPI's I/O forwarding.  Run manually via "
+        "examples/stoch_distr/go.bash to exercise this path until the root "
+        "cause is diagnosed."
+    )
     def test_values(self):
         command_line_pairs = [(f"mpiexec -np 3 python -u {python_args} -m mpi4py stoch_distr_admm_cylinders.py --num-stoch-scens 10 --num-admm-subproblems 2 --default-rho 10 --solver-name {solver_name} --max-iterations 50 --xhatxbar --lagrangian --rel-gap 0.001 --num-stages 3" \
                          , f"python {python_args} stoch_distr_ef.py --solver-name {solver_name} --num-stoch-scens 10 --num-admm-subproblems 2 --num-stages 3"), \