Omniverse Documentation Guidelines

Omniverse SDK documentation comes in five flavors:

  • SDK overview / design documentation

  • API documentation

  • Example applications

  • Source code comments

  • Project documentation

In order to drive Omniverse SDK adoption, Omniverse documentation targets new users. New users should be able to:

  • Have a uniform/predictable documentation consumption experience.

  • Answer all of their own questions without having to dive into implementation source code (headers are OK) or interview the original developer.

  • Easily understand the need, purpose, and benefits of using an SDK component.

  • Easily understand the concepts, objects, and components of an SDK component.

  • Be able to quickly start experimenting with the SDK.

This document provides ten guidelines as to when to write documentation, how to write documentation, and where to place it.

See Omniverse Documentation System for in-depth details on using the system.

Documentation System Goals

The primary goal of the Omniverse documentation system is accurate documentation. To achieve this, the documentation system relies on the following design decisions:

DG.1: SDK documentation lives with the source code. As source code is updated, documentation is also updated. Documentation is placed under the same review process as source code. Documentation does not live outside of the repo (e.g. a wiki) since external documentation is at best tied to a single snapshot of the SDK.

DG.2: All source code snippets are valid (i.e. will compile) and are unit tested. All source code snippets in the documentation are references to portions of source files within the repo. This ensures that all source code snippets can be compiled. By referencing source code snippets in unit tests, the documentation author can also verify that source snippet produces expected results. In some cases, this may require adding unit tests or examples that are used expressly for the purpose of documentation.

See Writing Unit Tested Code Examples to understand how to integrate your documentation with your testing framework.

DG.3: Documentation is high-quality.

  • Spelling and grammar are important.

  • Written in US English.

  • Consistent terminology and formatting.

Authoring Overview/Design Documents

The Omniverse SDK is a series of components. For example, the Framework component loads plugins while the windowing plugin provides platform agnostic interfaces to create, manipulate, and observe windows on a user’s desktop. This leads to the following guideline:

DG.4: Each component must provide an overview/design document, outlining:

  • What the component does

  • Why the component exists

  • Important design decisions

  • How to properly use the component

  • History of important changes to the component.

The resulting documentation must conform to the following format/location guidelines:

DG.5: Each component’s overview/design documentation must be:

  • Authored in reStructuredText. A complete guide tailored towards Omniverse, including how to ensure code snippets compile, can be found here.

  • Located at docs/<component>/ (e.g. docs/framework/)

The Omniverse documentation system uses Sphinx to transform the .rst files into user consumable documentation. A short guide to building documentation can be found at Quick Start Guide.

Authoring API Documentation

Each component in the SDK is composed of a public SDK.

DG.6: Each interface, class, struct, enum, method, function, member, macro, and constant in the public SDK must be documented using the Doxygen format. Documentation should contain the following:

  • What a class/interface/method/macro/member/struct/enum/function does

  • Any prerequisites for using the API

  • Outline any thread safety concerns

  • Denote the lifetime/ownership of memory/resources returned from a method/function

  • Denote the lifetime/ownership of memory passed into a method/function

  • Denote if nullptr is accepted, denied, or returned

  • Denote any applicable side effects of calling the method/function

  • Discuss any conflicts with other APIs, restrictions on use, where to acquire dependent parameters, etc

  • When using callbacks, specify if a callback will be called concurrently, if callbacks will be called on random threads, what APIs the callbacks are allowed to access, at what point a callback is guaranteed to no longer be invoked.

See Omniverse Doxygen Guide for how to use Doxygen to document your API.

Authoring Examples

For many, the primary way to learn a new API is by inspecting existing example code that uses the API. Examples are key in SDK adoption.

DG.7: Each component should provide (or be a part of) a fully-functional example application.

  • The example should live at source/examples/example.<component>

  • The example should strive to be minimal

Authoring Source Code Comments

Source code comments help future maintainers better understand the flow of a code block, the minute design decision made by the original author, and potential pitfalls with an implementation.

DG.8: Source code should be documented.

  • The descriptiveness of names should be proportional to their scope. Names with a very broad scope, such as externally visible API functions, should be as self-documenting as possible.

  • Document non-obvious things. Less is more.

Authoring Project Documentation

Some documentation isn’t component specific, rather, it deals with:

  • Checkout / getting started steps

  • Guidelines for dealing with the SDK/repo (e.g. how to contribute, coding style, etc.)

  • Overall SDK design/philosophy/overview.

  • Troubleshooting for common problems (e.g. build system troubleshooting).

DG.9: All non-component documentation should:

  • Appear in docs/. Subfolders of docs/ are allowed (e.g. docs/guidelines/).

  • Written in reStructuredText. An Omniverse specific authoring guide can be found here.

There are some exceptions to the guideline above:

DG.10: The following markdown files are allowed within the repo:

  • The repo must contain a top-level README.md. This file should contain an elevator pitch quickly followed by a link to the repo’s documentation.

  • Each component (e.g. source/omni/log/) may contain a README.md file. This file must simply point to the relevant .rst documentation.

Summary

In this document we outlined several guidelines on how to write accurate, uniform, and easy to consume documentation. While documentation can be a pain to initially author, good documentation empowers users to create without having to constantly interrupt the original API author for clarification and guidance.

As is the case with all guideline documents, there will not be consensus on the merits of each guideline. However, in order to produce high-quality, consistent documentation; documentation authors are expected to follow the guidelines above, regardless of their opinions of the effectiveness of each guideline.

Developers can begin integrating these guidelines via the Omniverse Documentation System by consulting the Quick Start Guide.