Remote content

Remote content#

2026-09-01

3 min read time

Use the remote-content directive to pull an .rst file from another GitHub repository into the current page at build time. It selects the branch or tag of the source repository that matches the version being built, so a release build inlines release content and a development build inlines development content.

Beyond inlining, the directive rewrites :doc: cross-references to external URLs (or remaps them to local pages), downloads referenced images, applies text and regex replacements, adds widths to CSV tables, and can fix common LaTeX math issues.

Enabling the extension#

The directive is opt-in. Add it to extensions in conf.py:

extensions = [
    "rocm_docs",
    "rocm_docs.remote_content",
]

Basic usage#

.. remote-content::
   :repo: ROCm/ROCm
   :path: docs/about/what-is-rocm.rst
   :default_branch: develop

On a release build (a docs-X.Y.Z branch, or a Read the Docs tag build), the directive fetches docs/about/what-is-rocm.rst from the matching tag. Otherwise it falls back to default_branch.

Version selection#

The target ref is chosen as follows:

  • If the build is a release (the version is X.Y.Z and one of: the local branch is a docs/ branch, READTHEDOCS_VERSION_TYPE is tag, or the version appears in the READTHEDOCS_VERSION slug), the ref is <tag_prefix><version>.

  • Otherwise the ref is default_branch.

If a release fetch fails (for example, the tag does not exist yet), the directive retries once against default_branch.

Options#

Option

Description

repo

Source repository as owner/name (required).

path

Path to the .rst file within the source repo (required).

default_branch

Branch to use when the build is not a release, and as the release fallback.

tag_prefix

Prefix prepended to the version to form the release tag (e.g. docs-).

start_line

Include the file starting from this line number.

replace

Literal text replacements, old|new, multiple separated by ;;.

replace_re

Regex replacements, pattern|replacement (DOTALL; \n in the replacement becomes a newline), multiple separated by ;;.

project_name

Override the project name used when building external :doc: URLs.

docs_base_url

Override the base URL used for external :doc: URLs.

doc_ignore

:doc: targets to leave unconverted, separated by ;;.

doc_remap

Remap :doc: targets to local pages: old|new or old|new_text|new, separated by ;;.

csv_widths

Add a :widths: value (e.g. 33 67) to CSV tables that lack one.

fix_latex_math

Set to true to escape underscores inside \text{} in math.

Handling :doc: references#

By default, each :doc: role in the fetched content is rewritten to an absolute URL on the published documentation site, so links resolve from the page that inlined the content. You can change this per target:

  • doc_ignore leaves a target as a normal :doc: role (useful when the target also exists locally or is resolved by intersphinx).

  • doc_remap rewrites a target to a different local page. Use old|new to keep the original link text, or old|new_text|new to also change the displayed text.

Namespaced references such as :doc:rocm:about/release-notes`` are left untouched so intersphinx can resolve them, unless a doc_remap entry matches.

Configuration#

The base URL used to build external :doc: links defaults to https://rocm.docs.amd.com/projects. Override it globally in conf.py:

rocm_docs_remote_content_docs_base = "https://rocm.docs.amd.com/projects"

The per-directive docs_base_url option takes precedence over this value.

Images#

Images referenced by the fetched content are downloaded into _remote_images/<owner>_<name>/ under the Sphinx source directory and the image nodes are updated to point at the local copies, so they render without depending on the remote host at serve time. Absolute image URLs are left unchanged.

Contents