doc: posix: structural reorganization of posix docs

[cfriedt]

Revise the structure of the POSIX API docs. This separates related items out to dedicated pages, see preview.

[cfriedt]

Was trying to disrupt all of the red (✅ = complete, 🏁 = nearly done, ⚠️ = in progress, ❌ = not yet started).

Suggestions @kartben ?

[cfriedt]

@kartben the things I would really like to do (in the future) are

• modify the Options in .rst so that POSIX functions link to a ref in doxygen (forward-ref)
• add a minimal doxygen entry for each POSIX function
• include a link in that doxygen entry back to the POSIX Option that it belongs to in .rst (backward-ref)

The problem is that there are a lot of POSIX functions.

Between the lines, that means it will be difficult to maintain manually (will bitrot, become inaccurate, etc).

IMHO, it makes a lot more sense to script this.

This PR intentionally doesn't include most of the above, in case we would like to backport it to v3.5-branch.

[kartben]

Thanks for this effort! Quite a few comments, but mostly cosmetics/formatting.

[kartben]

If you make it a subheading instead of a note, and have the heading spelled "Undefined behavior" (it will arguably make it stand even more, and will make it more clear for folks why they landed there when clicking on one of the "unsupported" links), then you can :ref:`posix_undefined_behaviour` directly in your table and it will already have a meaningful and usable title

[cfriedt]

Yeah, I'm not crazy about that standing out, to be honest.

[kartben]

The obelus feels very lonely and tiny in this column (and also hard to click for people and not very accessible).
See my comment re: how to change the note to a heading, and then this can simply become

Suggested change

	_POSIX_JOB_CONTROL, -1, :ref:`†<posix_undefined_behaviour>`
	_POSIX_JOB_CONTROL, -1, :ref:`posix_undefined_behaviour`

[cfriedt]

Yeah, again, I'm not super happy about lumping so many things into undefined behaviour. Ideally the gap would be significantly smaller but that also takes time and work. Additionally, I'd like to look at a better solution for generating these tables rather than maintaining them by hand.

[cfriedt]

@kartben - does it look OK for now? These POSIX doc changes were meant to be a backportable precursor to additional features in POSIX and POSIX configuration (which probably cannot be backported).

[kartben]

@kartben - does it look OK for now? These POSIX doc changes were meant to be a backportable precursor to additional features in POSIX and POSIX configuration (which probably cannot be backported).

mostly ok yes, thanks! I just added one more comment + you need a minor change to fix the currently broken build