gh-101100: Fix os.statvfs and os.uname references

[cmaloney]

Restructure descriptive paragraphs to class definitions copying across descriptions. Add constants from statvfs to os as data directives.

Expand the os.uname section slightly with a see also which matches the one at the beginning of os.rst added in gh-56535 commit a83cdaa.

This gets os.rst out of nitignore.

---

The statvfs_result members had no definition before and I opted not to add ones here. The C code in posixmodule.c just forwards them directly so I don't think a description would be more precise than what is in the man page.

• Issue: Fix all Sphinx reference warnings in the documentation #101100

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33209797 | 📁 Comparing de6f122 against main (84630e2)

  🔍 Preview build  

48 files changed · ± 48 modified

± Modified

• py-modindex.html
• c-api/bytes.html
• c-api/init_config.html
• c-api/stable.html
• c-api/type.html
• c-api/typeobj.html
• faq/gui.html
• howto/annotations.html
• howto/argparse.html
• howto/curses.html
• and 38 more...

[StanFromIreland]

Suggested change

	The return value is a :class:`uname_result` object whose attributes
	correspond to the members described in :manpage:`uname(2)`.
	The return value is a :class:`uname_result` object.

I think the note should be with the attributes ("These attributes correspond to the ...").

[cmaloney]

Misinterpreted this my first read, moved the manpage reference to the uname_result section

[serhiy-storchaka]

In general good, but I have other suggestions which you can implement here or leave to other PRs.

9 data classes are defined in the os module: DirEntry, sched_param, stat_result, statvfs_result, statx_result, terminal_size, times_result, uname_result, and waitid_result. 4 of them are not explicitly documented: stat_result, times_result, uname_result, and waitid_result.

Could you please document times_result and waitid_result too? Or you prefer to leave this to other PR?

Please check that all 9 classes use similar style (except that DirEntry and statx_result are not tuples).

And you can turn other mentions of uname_result (in NEWS entries) to references.

[serhiy-storchaka]

Maybe just refer to them as ``ST_*`` flags?

[cmaloney]

Worry that would be confusing with the stat module ST_* constants (https://docs.python.org/3/library/stat.html#stat.ST_MODE)

[cmaloney]

Want to keep this focused on getting the reference issues fixed (the issue this PR links to). I added short descriptions to the statvfs_result members. I like the short sentence between class and item so added, other dataclasses + flags should get.

Created gh-151684 for the followups.

[serhiy-storchaka]

LGTM. 👍

But note that reference-cleanest is not a goal by itself. It can be a measure, but the goal is the documentation completeness and clarity. When it became a goal, it stops to be measure.

[miss-islington-app]

Thanks @cmaloney for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @cmaloney for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @cmaloney for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-151690 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-151691 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-151692 is a backport of this pull request to the 3.15 branch.

[vstinner]

The 3.13 and 3.14 backports are stuck, Docs/Docs CI failed with warnings:

• [3.13] gh-101100: Document os.uname_result and os.statvfs_result with related constants (GH-151301) #151691
• [3.14] gh-101100: Document os.uname_result and os.statvfs_result with related constants (GH-151301) #151690

[serhiy-storchaka]

Yes, I am going to restore the ignore files.