Version Selection¶

As documentation evolves, it is important that the Omniverse Documentation System performs the following:

Allows for the co-existence of older versions of documentation with the latest documentation.
Makes it easy to discover the latest documentation.
Warns the user when the documentation they are reading may be out-of-date.

To achieve this, the documentation system:

Dynamically checks if the viewed documentation is the latest documentation, and if not, warns the user.
Provides a graphical affordance to select other versions of the documentation.

In order to enable these features, the project owner must publish a JSON file containing a list of valid documentation versions. The generation of the JSON file is automatic and is enabled by default on all projects. See Version Selector in Documentation for configuration details. The rest of this page defines the format used but this is probably not of interest if you are using repo docs to handle the entire process for you.

versions.json Format¶

An example versions.json is as follows:

{
    "latest": "0.9.1",
    "versions":
    [
        {
            "version": "0.9.1"
        },
        {
            "version": "0.8.1"
        },
        {
            "version": "0.7.1",
            "message": "This documentation is for an insecure version of repo_docs."
        }
    ]
}

Above, the message key is optional. All other fields are required.

Publishing versions.json¶

versions.json should be published to the project’s root directory. For example:

carbonite/
    versions.json
    index.html
    0.9.1/
        index.html
    0.8.1/
        index.html
    0.8.0/
        index.html
    0.7.1/
        index.html

If versions.json is not present in the published documentation, the documentation version selector and version check will not be present.

Advanced: Testing Version Selection with Local Builds¶

Testing version selection locally can be challenging for the following reasons:

The build system tries to maintain a single copy of the documentation.
Javascript is unable to read/fetch local files (due to security concerns).

However, testing of this feature is possible by going through the following hoops.

Local Web Server¶

A local web server must be created to allow Javascript to request needed files. This can easily be done with:

cd _build/docs
../../tools/packman/python -m http.server 10000

You can now browse to http://localhost:10000/ to view documentation.

Manually Create versions.json¶

Create a versions.json file and place it in your project’s documentation build root. As an example, if your project name is “carbonite”, you would create _build/docs/carbonite/versions.json.

See versions.json Format to understand the format of versions.json.