Linking Between Projects

The Omniverse Documentation system supports cross-referencing between projects. These projects can live in the same repo or in another repo.

To add a dependency to another project, use deps in repo.toml:

# deps can be used to link to other projects' documentation
deps = [
    [ "repo_docs-link-example", "_build/docs/repo_docs-link-example/latest" ],
]

deps is an array of pairs. Each pair contains a key and a directory where reference information can be found about the project. The directory must contain the following files:

• VERSION: The version of the documentation.

• objects.inv: Contains a database of available references in the documentation.

The key is used in :ref: statements as a domain in which the reference should be searched. For example, above I can link to the multiple_projects_overview reference in the nested-project project as follows:

:ref:`repo_docs-link-example:overview`

The above markup would produce the following link: Example: Linking to Another Project.

Limitations

There are several limitations when linking between projects.

Build Order

When building multiple projects in a repo, one project may depend upon another and as such will expect that its objects.inv exists when building. To control the build order of project within a repo, use project_build_order in repo.toml:

project_build_order = [ "repo_docs-link-example", "repo_docs", "nested-project", "project-with-extra-builds" ]

Note

This is expected to be fixed in the future.

Dependency Cycles

Currently, repo docs is unable to resolve all references between multiple projects if there are cycles in the project dependency graph. Said differently, if project A references project B, and project B references project A, repo docs will produce missing reference warnings.

The user can produce fully working documents by running the sphinx stage multiple times, though the first run of the sphinx stage will produce warnings. See Build Stages for more details.

Note

This is expected to be fixed in the future with the introduction of a link stage to repo docs.