Skip to content

Replace WASM includes in docs with logic in the directive itself #106867

Open

Description

@CAM-Gerlach

As originally brought up in #106861 , currently APIs/modules not available on WASM platforms use a Sphinx include to inject an availability directive and a stock description from wasm_notavail.rst, but this approach leaves no opportunity to add any other platforms/qualifiers to the availability list, among other issues.

A more flexible, extensible, and easier to use approach would be to simply list the platforms in availability as done everywhere else, and have the directive itself handle this case, and any others. This would handle any combination of WASM and non-WASM platforms and allows other platforms to be added as normal, avoids requiring doc writers to know to special-case WASM, and could be extended further for other platforms and customizations. Furthermore, it would relatively straightforward to implement, as availability is already a custom directive, enforces a constrained syntax and validates platform names, so parsing and checking for this handling wouldn't require any additional logic.

To avoid further overloading the directive code with bespoke content and special-casing, and make this easy to configure going forward, the custom content would be stored in a mapping of platform names to values in conf.py; in fact, given this it would actually be simpler and more natural to just specify the rest of the known platform names too as dict keys (i.e. a set), so there's no need to hardcode them in the directive itself at all, making it fully generic, configurable and usable on any project (and could later be upstreamed or spun out, like sphinx-lint).

A literal 1:1 reproduction of the current usage would be to inject a custom content paragraph for certain platform names. However, it was also suggested to link the platform names to a section explaining them; given implementing the latter is simpler, cleaner and more concise (in code, config and output) while accomplishing essentially the same thing as the current description inject (which just restates the platform availability qualifiers in a more verbose fashion and refers the reader to just such a section for more information), I propose we just do that.

Metadata

Metadata

Assignees

Labels

OS-wasidocsDocumentation in the Doc dir

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions