Fix stale method names in the Python API docstrings

[hakonhagland]

Four methods in the generated Python API reference are documented under names that do not exist, so a reader who follows the published reference gets an AttributeError. The names in python/docstrings_simulators.json were not updated when the bindings python/simulators/Py*Simulator.cpp were renamed.

documented as	actually bound as
mpi_init	setup_mpi
get_fluid_state_variable	get_fluidstate_variable
get_primary_var_meaning	get_primary_variable_meaning
get_primary_var_meaning_map	get_primary_variable_meaning_map

This only affects the generated documentation page. help() in Python is unaffected, because pybind11 builds that signature line from the binding itself and it already shows the correct names.

Note: Found while reviewing OPM/opm-python-documentation#31. That review exposed the issue addressed by this PR.

Fix stale method names in the docstring templates (commit 1)

• Each entry in docstrings_simulators.json has a signature_template, and the Sphinx extension renders the method name from that template rather than from the binding — so a stale template silently publishes a name that cannot be called.
• Corrected the four templates to the names actually passed to .def() in python/simulators/Py*Simulator.cpp.
• Only the templates were stale. The docstring bodies already use the correct names — the getPrimaryVarMeaning text, for instance, refers the reader to get_primary_variable_meaning_map().

Fix a broken literal in the setup_mpi docstring (commit 2)

• The :param finalize: line closed its inline literal with three backticks instead of two, and had no space before the next word:

  :param finalize: Whether to call ``MPI_Finalize()```when the simulator object goes out of scope.
  

• reStructuredText does not recognize that as a literal, so the page shows the backticks themselves.

• Unlike the signature templates, this text is compiled into the binding, so help(sim.setup_mpi) shows the stray backticks too.

Restore alphabetical order of the documented methods (commit 3)

• The generated page lists methods in the order the entries appear in the JSON file. With the stale names that order happened to be alphabetical, because get_primary_var_meaning sorts before get_primary_variable; with the real names it no longer is.
• Moved getPrimaryVariable ahead of getPrimaryVarMeaning. No text changes — only the position of the entry. Kept as a separate commit so it can be dropped if reviewers would rather not have the churn.

Verification

• Cross-checked every entry in common_methods against the methods actually bound, then confirmed against the imported module with hasattr rather than by reading the source.
• Rebuilt the documentation page from the patched file: mpi_init, get_fluid_state_variable and get_primary_var_meaning now appear zero times, the rendered method list matches the module's dir() exactly and in the same order, and the setup_mpi entry reads "Whether to call MPI_Finalize() when the simulator object goes out of scope" with no stray backticks.

[hakonhagland]

jenkins build this please

[Copilot]

Copilot review overview

🟢 Approval recommended

The documentation now matches the bound methods and has no unresolved blocking issues.

Review effort: Lite
Findings: None

What changed in this PR

Updates generated Python API documentation to match the actual simulator bindings.

Changes:

• Corrects four stale method signatures.
• Fixes malformed MPI_Finalize() literal markup.
• Restores alphabetical method ordering.

File	Summary
python/​docstrings_simulators.json	Updates signatures, documentation formatting, and method ordering.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[blattms]

Looks good. Does the deployment happen after the merge?

[hakonhagland]

Does the deployment happen after the merge?

@blattms Yes it should, see

opm-simulators/.github/workflows/dispatch_opm_simulators.yml

Line 7 in 14056e8

- 'python/docstrings_simulators.json'

It watches the file that this PR changes, and sends a repository_dispatch signal to the other repo. Which should deploy the docs.

[hakonhagland]

@blattms Following up on my own answer: the deployment did not happen.

The dispatch job ran three seconds after the merge and reported success, but its log has this in it:

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest",
  "status": "401"
}

https://github.com/OPM/opm-simulators/actions/runs/35892130973/job/107286916833

So the PERSONAL_ACCESS_TOKEN secret in this repository is no longer valid — expired, revoked or rotated, a 401 does not say which. The job is green because the step is a bare curl with no --fail and no status check, so the 401 body is printed and curl still exits 0.

Confirmed on both ends: master now has the corrected setup_mpi signature, while the published page at https://opm.github.io/opm-python-documentation/master/simulators.html still shows mpi_init 15 times and setup_mpi not at all. opm-python-documentation has had no repository_dispatch run since 2025-09-23, and its gh-pages branch has not been touched since before the merge.

This has probably been broken for a while rather than being new — python/docstrings_simulators.json had not changed on master since 2025-09-23, so this PR is simply the first change since the token stopped working, and the first time it mattered.

Two things that would help, if you agree:

1. Renew the PERSONAL_ACCESS_TOKEN secret here. That needs admin on this repository — could you do it? Until then every future docstring change will silently fail to publish.
2. Make the failure loud. Adding --fail-with-body to the curl in .github/workflows/dispatch_opm_simulators.yml would have turned this into a red job a year ago instead of a silent no-op. Happy to open a small PR for that.

I will also propose adding a workflow_dispatch: trigger to python_sphinx_docs.yml on the documentation side, since there is currently no manual way to re-run the build when the dispatch fails.

In the meantime I can get the current docs published by triggering the documentation build directly, so the merged fix does not sit unpublished while the token is sorted out.

[hakonhagland]

@blattms Published now. Triggered the documentation build by hand, sending the same event the automatic dispatch would have sent, but with my own credentials instead of the repository secret:

gh api --method POST repos/OPM/opm-python-documentation/dispatches \
  -f event_type=docstrings_simulators_updated