Discuss Standard into Sphinx and possible alignment w/ OpenPMIx library releases

[naughtont3]

Overview

From the ASC 2026 Q1 meeting, a discussion item was raised about whether and how to move PMIx Standard Specification text into Sphinx documentation, and secondly connect it with the OpenPMIx library releases.

Goal

Discuss and agree on value/benefits, feasibility and approach for consideration to:

• a) move Standard text into Sphinx docs, and
• b) whether it should align/merge with OpenPMIx releases

Discussion Points

• What content should move to Sphinx vs remain in the LaTeX Standards Spec
• Effort and risks of migration
• Versioning and release coupling with OpenPMIx library
• Expected benefits for users and maintainers

[naughtont3]

My thoughts on items:

• (Item A) I would be fine with moving things from LaTeX to Sphinx, but fear that could be a lot of work. It would probably only make sense if community thinks that Item B is yes.
• (Item B) I fear this moves things away from attempting to be a Standard specification and closer to Implementation documentation. I could possibly be convinced, but lean toward keeping Standard spec independent.

[rhc54]

I think there has been some misunderstanding. I have zero interest in converting the current Standard into Sphinx - if someone else wants to do it, more power to them.

What I'm doing is creating man pages in the OpenPMIx releases, one for each PMIx API plus some to cover things like attributes and explanations of how-things-work. Those man pages will be based on extractions from the Standard, converted to Sphinx. The man pages distributed with each release will therefore accurately describe the behavior and supported attributes for each API at that time.

I will be adding to that material as things continue to evolve: updating descriptions to reflect changes that get made, adding attributes and an API or two, etc. Since I appear to be the only one adding material at this time, I'm not too inclined to make those changes twice - once in the man pages, and again in the Tex pages.

So my question was more of: how do folks want to handle coordinating the docs? I believe I can get Sphinx to drop a pdf version of the man pages - pretty sure it won't generate Tex, and no way that would deal with all the special macros in the Standard. Not sure if/how that helps.

If folks want to manually carry across the updates, that's fine with me. I just can't take on the added burden.