Sphinx

Cross-referencing symbols

Sphinx provides several roles to create cross-references to Python symbols in the extra_platforms module. These roles work in both MyST Markdown and reStructuredText formats.

Available roles

• {func} — Reference a function (e.g., is_linux(), current_traits())

• {data} — Reference a module-level constant (e.g., UBUNTU, skip_linux)

• {class} — Reference a class (e.g., Platform, Architecture, Group)

• {mod} — Reference a module (e.g., detection)

Note

Pytest decorators like skip_linux are MarkDecorator objects. Use {data} for inline cross-references. For API documentation, the built-in autodecorator directive renders them with the @ prefix (see pytest.md).

Syntax

MyST Markdown

Use curly braces and backticks:

Check the current platform with {func}`~extra_platforms.is_linux`.

The {class}`~extra_platforms.Platform` class represents operating systems.

Pre-defined platforms like {data}`~extra_platforms.UBUNTU` are available.

See the {mod}`extra_platforms.detection` module for detection functions.

reStructuredText

Use colons and backticks:

Check the current platform with :func:`~extra_platforms.is_linux`.

The :class:`~extra_platforms.Platform` class represents operating systems.

Pre-defined platforms like :data:`~extra_platforms.UBUNTU` are available.

See the :mod:`extra_platforms.detection` module for detection functions.

Which renders as:

Check the current platform with is_linux().

The Platform class represents operating systems.

Pre-defined platforms like UBUNTU are available.

See the extra_platforms.detection module for detection functions.

The tilde (~) prefix displays only the symbol name without the full module path:

• `{func}`~extra_platforms.is_linux` renders as is_linux()

• `{func}`extra_platforms.is_linux` renders as extra_platforms.is_linux()

Setting a default module

To avoid repeating the module name, use the currentmodule directive:

MyST Markdown

```{py:currentmodule} extra_platforms
```

Use {func}`is_linux` or {func}`is_windows` to check platforms.

reStructuredText

.. py:currentmodule:: extra_platforms

Use :func:`is_linux` or :func:`is_windows` to check platforms.

Which renders as:

Use is_linux() or is_windows() to check platforms.

Cross-reference resolution

Symbols exposed at the root extra_platforms module automatically link to their actual definition location:

• current_traits() links to detection.html

• Platform links to trait.html

• UBUNTU links to platform_data.html

This ensures documentation remains accurate even when symbols are re-exported from submodules.

Reference matrix

This section demonstrates all syntax variations for referencing different object types in the extra_platforms module. All examples use the short-path format with the currentmodule directive.

MyST syntax	Rendering	Description
		Traits
{data}`~UBUNTU`	UBUNTU	Platform trait symbol
{func}`~is_ubuntu`	is_ubuntu()	Platform trait detection function
{data}`~pytest.skip_ubuntu`	skip_ubuntu	Platform trait skip decorator
{data}`~pytest.unless_ubuntu`	unless_ubuntu	Platform trait unless decorator
{data}`~AARCH64`	AARCH64	Architecture trait symbol
{func}`~is_aarch64`	is_aarch64()	Architecture trait detection function
{data}`~pytest.skip_aarch64`	skip_aarch64	Architecture trait skip decorator
{data}`~pytest.unless_aarch64`	unless_aarch64	Architecture trait unless decorator
{data}`~GITHUB_CI`	GITHUB_CI	CI trait symbol
{func}`~is_github_ci`	is_github_ci()	CI trait detection function
{data}`~pytest.skip_github_ci`	skip_github_ci	CI trait skip decorator
{data}`~pytest.unless_github_ci`	unless_github_ci	CI trait unless decorator
		Groups
{data}`~LINUX`	LINUX	Regular group symbol
{func}`~is_linux`	is_linux()	Regular group detection function
{data}`~pytest.skip_linux`	skip_linux	Regular group skip decorator
{data}`~pytest.unless_linux`	unless_linux	Regular group unless decorator
{data}`~ALL_PLATFORMS`	ALL_PLATFORMS	ALL_* group symbol
{func}`~is_any_platform`	is_any_platform()	ALL_* group detection function
{data}`~pytest.skip_all_platforms`	skip_all_platforms	ALL_* group skip decorator
{data}`~pytest.unless_any_platform`	unless_any_platform	ALL_* group unless decorator
{data}`~UNKNOWN_PLATFORM`	UNKNOWN_PLATFORM	Unknown platform symbol
{func}`~is_unknown_platform`	is_unknown_platform()	Unknown platform detection function
{data}`~pytest.skip_unknown_platform`	skip_unknown_platform	Unknown platform skip decorator
{data}`~pytest.unless_unknown_platform`	unless_unknown_platform	Unknown platform unless decorator
{data}`~UNKNOWN_ARCHITECTURE`	UNKNOWN_ARCHITECTURE	Unknown architecture symbol
{func}`~is_unknown_architecture`	is_unknown_architecture()	Unknown architecture detection function
{data}`~pytest.skip_unknown_architecture`	skip_unknown_architecture	Unknown architecture skip decorator
{data}`~pytest.unless_unknown_architecture`	unless_unknown_architecture	Unknown architecture unless decorator
{data}`~UNKNOWN_CI`	UNKNOWN_CI	Unknown CI symbol
{func}`~is_unknown_ci`	is_unknown_ci()	Unknown CI detection function
{data}`~pytest.skip_unknown_ci`	skip_unknown_ci	Unknown CI skip decorator
{data}`~pytest.unless_unknown_ci`	unless_unknown_ci	Unknown CI unless decorator
{data}`~UNIX_WITHOUT_MACOS`	UNIX_WITHOUT_MACOS	Group with _without_ (translated to _not_ in function)
{func}`~is_unix_not_macos`	is_unix_not_macos()	Group function with _without_ → _not_ translation
		Detection Methods
{func}`~current_platform`	current_platform()	Current platform detection function
{func}`~current_architecture`	current_architecture()	Current architecture detection function
{func}`~current_ci`	current_ci()	Current CI detection function
{func}`~current_traits`	current_traits()	All current traits detection function
		Classes
{class}`~Platform`	Platform	Platform trait class
{class}`~Architecture`	Architecture	Architecture trait class
{class}`~CI`	CI	CI trait class
{class}`~Group`	Group	Group class
		Utilities
{func}`~reduce`	reduce()	Reduce utility function
{func}`~invalidate_caches`	invalidate_caches()	Cache invalidation utility function

Tip

All the examples in this reference matrix are tested in tests/test_sphinx_crossrefs.py to ensure cross-references resolve correctly in the built documentation.