Repository navigation
Unix-only pages should each say "Availability: Unix" #106861
Description
Documentation
This section of the docs has a number of pages: https://docs.python.org/3/library/unix.html . Each is only available on Unix, but the pages themselves don't say this. For example, if you search for the resource module, you get to here: https://docs.python.org/3/library/resource.html, and nothing on that page says it's not available on Windows.
It would be a small change to add "Availability: Unix" to each of these pages to make them more self-contained and quicker to reference.
Activity
CAM-Gerlach commentedon Jul 18, 2023
Additionally, some of them actually already have an
availabilitydirective (via thewasm_notavail.rstinclude) that only lists as its contentsnot Emscripten, not WASIthat implies it is available on other platforms. Unfortunately, the rather crude nature of that currently being done as an include makes it not possible to add any other qualifiers to theavailabilitydirective.Add the appropriate logic to the directive itself (as its already a custom directive, enforces a constrained syntax and parses platform names) to insert the appropriate descriptive content if
not Emscripten, not WASIare listed as platforms. To avoid further overloading the directive code with bespoke content and special-casing, and make this easy to configure in the future, this would be stored in theconf.py, along with the known platform names, as a mapping from platform names to standard description content to inject.To note, this would also easily allow for auto-cross-referencing platforms named in directives to, e.g. sections describing their current status in Python, configured via the same mechanism. In fact, this could preclude the need for custom
descriptioninjects at all, the existing usage just slightly elaborates on the base directive content and directs the users to such a section for more information.CAM-Gerlach commentedon Jul 18, 2023
I opened #106867 to cover the directive improvements discussed above that are required by this issue.
pythongh-106861: add availability on unix-only pages
pythongh-106861: add availability on unix-only pages
pythongh-106861: add availability on unix-only pages
gh-106861: Docs: Add availability directives to all Unix-only modules (…
pythongh-106861: Docs: Add availability directives to all Unix-only m…
pythongh-106861: Docs: Add availability directives to all Unix-only m…
hugovk commentedon Oct 31, 2023
#108975 has been merged and backports will be soon. Thanks!
[3.12] gh-106861: Docs: Add availability directives to all Unix-only …
[3.11] gh-106861: Docs: Add availability directives to all Unix-only …
pythongh-106861: Docs: Add availability directives to all Unix-only m…
pythongh-106861: Docs: Add availability directives to all Unix-only m…
pythongh-106861: Docs: Add availability directives to all Unix-only m…