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.