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	reST syntax	Rendering	Description
			Traits
{data}`~UBUNTU`	:data:`~UBUNTU`	UBUNTU	Platform trait symbol
{func}`~is_ubuntu`	:func:`~is_ubuntu`	is_ubuntu()	Platform trait detection function
{data}`~pytest.skip_ubuntu`	:data:`~pytest.skip_ubuntu`	skip_ubuntu	Platform trait skip decorator
{data}`~pytest.unless_ubuntu`	:data:`~pytest.unless_ubuntu`	unless_ubuntu	Platform trait unless decorator
{data}`~AARCH64`	:data:`~AARCH64`	AARCH64	Architecture trait symbol
{func}`~is_aarch64`	:func:`~is_aarch64`	is_aarch64()	Architecture trait detection function
{data}`~pytest.skip_aarch64`	:data:`~pytest.skip_aarch64`	skip_aarch64	Architecture trait skip decorator
{data}`~pytest.unless_aarch64`	:data:`~pytest.unless_aarch64`	unless_aarch64	Architecture trait unless decorator
{data}`~BASH`	:data:`~BASH`	BASH	Shell trait symbol
{func}`~is_bash`	:func:`~is_bash`	is_bash()	Shell trait detection function
{data}`~pytest.skip_bash`	:data:`~pytest.skip_bash`	skip_bash	Shell trait skip decorator
{data}`~pytest.unless_bash`	:data:`~pytest.unless_bash`	unless_bash	Shell trait unless decorator
{data}`~GITHUB_CI`	:data:`~GITHUB_CI`	GITHUB_CI	CI trait symbol
{func}`~is_github_ci`	:func:`~is_github_ci`	is_github_ci()	CI trait detection function
{data}`~pytest.skip_github_ci`	:data:`~pytest.skip_github_ci`	skip_github_ci	CI trait skip decorator
{data}`~pytest.unless_github_ci`	:data:`~pytest.unless_github_ci`	unless_github_ci	CI trait unless decorator
{data}`~KITTY`	:data:`~KITTY`	KITTY	Terminal trait symbol
{func}`~is_kitty`	:func:`~is_kitty`	is_kitty()	Terminal trait detection function
{data}`~pytest.skip_kitty`	:data:`~pytest.skip_kitty`	skip_kitty	Terminal trait skip decorator
{data}`~pytest.unless_kitty`	:data:`~pytest.unless_kitty`	unless_kitty	Terminal trait unless decorator
{data}`~CLAUDE_CODE`	:data:`~CLAUDE_CODE`	CLAUDE_CODE	Agent trait symbol
{func}`~is_claude_code`	:func:`~is_claude_code`	is_claude_code()	Agent trait detection function
{data}`~pytest.skip_claude_code`	:data:`~pytest.skip_claude_code`	skip_claude_code	Agent trait skip decorator
{data}`~pytest.unless_claude_code`	:data:`~pytest.unless_claude_code`	unless_claude_code	Agent trait unless decorator
			Groups
{data}`~LINUX`	:data:`~LINUX`	LINUX	Regular group symbol
{func}`~is_linux`	:func:`~is_linux`	is_linux()	Regular group detection function
{data}`~pytest.skip_linux`	:data:`~pytest.skip_linux`	skip_linux	Regular group skip decorator
{data}`~pytest.unless_linux`	:data:`~pytest.unless_linux`	unless_linux	Regular group unless decorator
{data}`~ALL_PLATFORMS`	:data:`~ALL_PLATFORMS`	ALL_PLATFORMS	ALL_* group symbol
{func}`~is_any_platform`	:func:`~is_any_platform`	is_any_platform()	ALL_* group detection function
{data}`~pytest.skip_all_platforms`	:data:`~pytest.skip_all_platforms`	skip_all_platforms	ALL_* group skip decorator
{data}`~pytest.unless_any_platform`	:data:`~pytest.unless_any_platform`	unless_any_platform	ALL_* group unless decorator
{data}`~ALL_SHELLS`	:data:`~ALL_SHELLS`	ALL_SHELLS	ALL_* shell group symbol
{func}`~is_any_shell`	:func:`~is_any_shell`	is_any_shell()	ALL_* shell group detection function
{data}`~pytest.skip_all_shells`	:data:`~pytest.skip_all_shells`	skip_all_shells	ALL_* shell group skip decorator
{data}`~pytest.unless_any_shell`	:data:`~pytest.unless_any_shell`	unless_any_shell	ALL_* shell group unless decorator
{data}`~ALL_TERMINALS`	:data:`~ALL_TERMINALS`	ALL_TERMINALS	ALL_* terminal group symbol
{func}`~is_any_terminal`	:func:`~is_any_terminal`	is_any_terminal()	ALL_* terminal group detection function
{data}`~pytest.skip_all_terminals`	:data:`~pytest.skip_all_terminals`	skip_all_terminals	ALL_* terminal group skip decorator
{data}`~pytest.unless_any_terminal`	:data:`~pytest.unless_any_terminal`	unless_any_terminal	ALL_* terminal group unless decorator
{data}`~ALL_AGENTS`	:data:`~ALL_AGENTS`	ALL_AGENTS	ALL_* agent group symbol
{func}`~is_any_agent`	:func:`~is_any_agent`	is_any_agent()	ALL_* agent group detection function
{data}`~pytest.skip_all_agents`	:data:`~pytest.skip_all_agents`	skip_all_agents	ALL_* agent group skip decorator
{data}`~pytest.unless_any_agent`	:data:`~pytest.unless_any_agent`	unless_any_agent	ALL_* agent group unless decorator
{data}`~UNKNOWN_PLATFORM`	:data:`~UNKNOWN_PLATFORM`	UNKNOWN_PLATFORM	Unknown platform symbol
{func}`~is_unknown_platform`	:func:`~is_unknown_platform`	is_unknown_platform()	Unknown platform detection function
{data}`~pytest.skip_unknown_platform`	:data:`~pytest.skip_unknown_platform`	skip_unknown_platform	Unknown platform skip decorator
{data}`~pytest.unless_unknown_platform`	:data:`~pytest.unless_unknown_platform`	unless_unknown_platform	Unknown platform unless decorator
{data}`~UNKNOWN_ARCHITECTURE`	:data:`~UNKNOWN_ARCHITECTURE`	UNKNOWN_ARCHITECTURE	Unknown architecture symbol
{func}`~is_unknown_architecture`	:func:`~is_unknown_architecture`	is_unknown_architecture()	Unknown architecture detection function
{data}`~pytest.skip_unknown_architecture`	:data:`~pytest.skip_unknown_architecture`	skip_unknown_architecture	Unknown architecture skip decorator
{data}`~pytest.unless_unknown_architecture`	:data:`~pytest.unless_unknown_architecture`	unless_unknown_architecture	Unknown architecture unless decorator
{data}`~UNKNOWN_SHELL`	:data:`~UNKNOWN_SHELL`	UNKNOWN_SHELL	Unknown shell symbol
{func}`~is_unknown_shell`	:func:`~is_unknown_shell`	is_unknown_shell()	Unknown shell detection function
{data}`~pytest.skip_unknown_shell`	:data:`~pytest.skip_unknown_shell`	skip_unknown_shell	Unknown shell skip decorator
{data}`~pytest.unless_unknown_shell`	:data:`~pytest.unless_unknown_shell`	unless_unknown_shell	Unknown shell unless decorator
{data}`~UNKNOWN_CI`	:data:`~UNKNOWN_CI`	UNKNOWN_CI	Unknown CI symbol
{func}`~is_unknown_ci`	:func:`~is_unknown_ci`	is_unknown_ci()	Unknown CI detection function
{data}`~pytest.skip_unknown_ci`	:data:`~pytest.skip_unknown_ci`	skip_unknown_ci	Unknown CI skip decorator
{data}`~pytest.unless_unknown_ci`	:data:`~pytest.unless_unknown_ci`	unless_unknown_ci	Unknown CI unless decorator
{data}`~UNKNOWN_TERMINAL`	:data:`~UNKNOWN_TERMINAL`	UNKNOWN_TERMINAL	Unknown terminal symbol
{func}`~is_unknown_terminal`	:func:`~is_unknown_terminal`	is_unknown_terminal()	Unknown terminal detection function
{data}`~pytest.skip_unknown_terminal`	:data:`~pytest.skip_unknown_terminal`	skip_unknown_terminal	Unknown terminal skip decorator
{data}`~pytest.unless_unknown_terminal`	:data:`~pytest.unless_unknown_terminal`	unless_unknown_terminal	Unknown terminal unless decorator
{data}`~UNKNOWN_AGENT`	:data:`~UNKNOWN_AGENT`	UNKNOWN_AGENT	Unknown agent symbol
{func}`~is_unknown_agent`	:func:`~is_unknown_agent`	is_unknown_agent()	Unknown agent detection function
{data}`~pytest.skip_unknown_agent`	:data:`~pytest.skip_unknown_agent`	skip_unknown_agent	Unknown agent skip decorator
{data}`~pytest.unless_unknown_agent`	:data:`~pytest.unless_unknown_agent`	unless_unknown_agent	Unknown agent unless decorator
{data}`~UNIX_WITHOUT_MACOS`	:data:`~UNIX_WITHOUT_MACOS`	UNIX_WITHOUT_MACOS	Group with _without_ (translated to _not_ in function)
{func}`~is_unix_not_macos`	:func:`~is_unix_not_macos`	is_unix_not_macos()	Group function with _without_ → _not_ translation
			Detection Methods
{func}`~current_platform`	:func:`~current_platform`	current_platform()	Current platform detection function
{func}`~current_architecture`	:func:`~current_architecture`	current_architecture()	Current architecture detection function
{func}`~current_shell`	:func:`~current_shell`	current_shell()	Current shell detection function
{func}`~current_ci`	:func:`~current_ci`	current_ci()	Current CI detection function
{func}`~current_terminal`	:func:`~current_terminal`	current_terminal()	Current terminal detection function
{func}`~current_agent`	:func:`~current_agent`	current_agent()	Current agent detection function
{func}`~current_traits`	:func:`~current_traits`	current_traits()	All current traits detection function
			Classes
{class}`~Platform`	:class:`~Platform`	Platform	Platform trait class
{class}`~Architecture`	:class:`~Architecture`	Architecture	Architecture trait class
{class}`~Shell`	:class:`~Shell`	Shell	Shell trait class
{class}`~Terminal`	:class:`~Terminal`	Terminal	Terminal trait class
{class}`~CI`	:class:`~CI`	CI	CI trait class
{class}`~Agent`	:class:`~Agent`	Agent	Agent trait class
{class}`~Trait`	:class:`~Trait`	Trait	Base trait class
{class}`~Group`	:class:`~Group`	Group	Group class
			Utilities
{func}`~reduce`	:func:`~reduce`	reduce()	Reduce utility function
{func}`~extract_members`	:func:`~extract_members`	extract_members()	Extract group members utility function
{func}`~traits_from_ids`	:func:`~traits_from_ids`	traits_from_ids()	Traits from IDs utility function
{func}`~groups_from_ids`	:func:`~groups_from_ids`	groups_from_ids()	Groups from IDs utility function
{func}`~invalidate_caches`	: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.

Third-party cross-references

Other projects can link to extra_platforms symbols in their own Sphinx documentation via intersphinx.

Setup

Add extra_platforms to the intersphinx_mapping in your project’s conf.py:

extensions = [
    "sphinx.ext.intersphinx",
    # ...
]

intersphinx_mapping = {
    "extra_platforms": ("https://kdeldycke.github.io/extra-platforms/", None),
}

Syntax

Cross-references use the inventory:target format. The inventory name is extra_platforms (matching the key in intersphinx_mapping), and the target is the fully-qualified Python symbol:

MyST Markdown

Skip this test on Linux with {data}`extra_platforms:extra_platforms.pytest.skip_linux`.

Detect macOS at runtime with {func}`extra_platforms:extra_platforms.is_macos`.

The {class}`extra_platforms:extra_platforms.Group` class supports set operations.

Use {data}`extra_platforms:extra_platforms.UBUNTU` for the Ubuntu platform constant.

reStructuredText

Skip this test on Linux with :data:`extra_platforms:extra_platforms.pytest.skip_linux`.

Detect macOS at runtime with :func:`extra_platforms:extra_platforms.is_macos`.

The :class:`extra_platforms:extra_platforms.Group` class supports set operations.

Use :data:`extra_platforms:extra_platforms.UBUNTU` for the Ubuntu platform constant.

The tilde (~) prefix works the same way with the inventory qualifier:

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

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

Inspecting the inventory

To list all available symbols in the published inventory:

$ python -m sphinx.ext.intersphinx https://kdeldycke.github.io/extra-platforms/objects.inv