List of Documentation System Hacks

A goal of the Omniverse Documentation System is to rely on Open Source Software to make developing and maintaing the overall system easier. However, during development, we’ve made the following hacks to tailor the system to Omniverse’s needs:

References in toctre

Stock Sphinx is only able to reference absolute URLs and documents in .. toctree:: directives. We’ve modified the .. toctree:: directive to additionally accept references to headings via :ref:. For example:

.. toctree::
    :caption: Example Docs
    :hidden:

    C++ API <_build/docs/repo_docs/latest/repo_docs_api>
    :ref:`Multiple Projects in a Repo <nested-project:multiple_projects_overview>`
    :ref:`Multiple Builds in a Repo <project-with-extra-builds:extra_builds_overview>`

Warning

When using :ref: in .. toctree::, only link to references in other projects. While linking to references within the same project is supported, the resulting HTML doesn’t look good.

Customized Exhale Output

Many customization have been made to the .rst Exhale produces to better suite Omniverse’s needs.

Exhale Exits After Running

We’ve updated Exhale to quit after .rst generation. This fits more inline with our multi-stage build approach.

ifconfig Runs Earlier in the Build

In stock Sphinx, children of .. ifconfig are removed after references have been resolved. This means that a build that conditionally includes documents may produce warnings about missing references. We’ve updated Sphinx to remove .. ifconfig::’s children before reference resolution to avoid any warnings.