External Intersphinx Project Mapping

2025-05-07

3 min read time

Projects should be defined in projects.yaml and should set which key they correspond to by setting external_projects_current_project to this key.

Example

Given the following projects.yaml file:

projects:
  python: https://docs.python.org/3/
  rtd: https://docs.readthedocs.io/en/stable/
  sphinx: https://www.sphinx-doc.org/en/master/
  rocm-docs-core: https://rocm.docs.amd.com/projects/rocm-docs-core/en/${version}

The conf.py from rocm-docs-core should contain:

external_projects_current_project = "rocm-docs-core"

Adds support for specifying the “development” branch for each project defined in projects.yaml. This is achieved by setting the development_branch key for the project:

projects:
  ...
  project:
    target: <target-url>
    development_branch: master

With this the mapping between projects is changed to the following:

Development branches map between each other. Essentially, links on project A’s develop branch point to the project B’s master branch. Vice-versa if A has set its development_branch to develop and B sets it to master.

Symbolic versions “latest” and “stable” map to themselves in other projects.

Any other branch maps to “latest”.

Explicitly list external projects

By default the inventories of all external projects defined in projects.yaml will be downloaded. This can take a long time as it requires a network request for each external project.

The external_projects configuration option can be set to a list with the names of remote projects to fetch inventories from & enable links to. The list must be a subset of the project names defined in projects.yaml. The default value of "all" means to fetch all projects.

Intersphinx references to projects that are not in external_projects will not be resolved. References in the the TOC like ${project:project_name} will continue to be resolved to the URL of project_name, even if project_name is not set in external_projects (but it’s defined in projects.yaml).