Publishing Documentation¶

Documentation is only useful if it’s published for consumption. The Omniverse documentation system contains multiple methods to make publishing documentation easy.

repo.toml can contain publishing settings for multiple editions of the documentation. Each edition of the documentation can contain unique settings to define where/how the documentation is published.

Publishing settings are stored in the [repo_docs.editions] table. For example, below we define the review edition:

[repo_docs.editions.review]
protocol = "git"

# git repo that stores the rendered (html) documentation
repo_url = "http://docvm-2.ov.nvidia.com/git/foundation-internal"

# specifies the sub-directory of the repo into which the HTML should be copied.
#
# defaults to "." (i.e. the root of the remote repo)
repo_project_dir = "${project}"

Above, we see that a git repo is used to store the rendered HTML documentation. In the following example we define the s3web edition using AWS S3 for hosting the static website:

[repo_docs.editions.s3web]
protocol = "s3"

# the bucket used in s3 to host the rendered (html) documentation
# the environment must be configured with proper credentials so that
# we can read, write, create, delete in the target path inside the bucket.
#
# we recommend using environment variables:
# - AWS_ACCESS_KEY_ID
# - AWS_SECRET_ACCESS_KEY
# but other methods are possible, see
# https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html
bucket_name = "omniverse-docs"

# the region where the s3 bucket is hosted.
# we recommend using this setting but region can alternatively be specified via
# - AWS_DEFAULT_REGION
# environment variable.
region = "us-east-1"

# specifies the target path within the bucket that the documentation will
# be copied to
#
# defaults to "${version}" (i.e. the root of the bucket with a version
# subfolder); available keywords are ${project}, ${version}, and ${build}
bucket_dir = "${project}/${version}"

Version Selector in Documentation¶

By default a version selector is enabled for the documentation published, listing all versions that have been published to the web server. If this is not desired it can be disabled:

version_selector_enabled = false

This setting can be specified within project scope or within a edition to disable it for all projects published in that edition.

Additionally, users can include a message with a version if there is important information to convey to the reader for that version:

version_selector_notes = [
    [ "0.9.3", "This version had a few path handling bugs - please use a newer version."],
]

Publishing via the Command Line¶

Publishing is handled by the publish stage (see Build Stages). By default, the publish stage does not run. To run the publish stage:

repo docs --stage publish --edition review

When running the publish stage, the --edition option can be used to only publish editions matching the name provided. To publish multiple editions the option can be repeated. If the edition option is not included all editions will be published. For simple projects, it’s common to only have one edition specified in repo.toml and therefore the --edition option is never used.

While --edition flag can be used to define where docs are published, additional flags may be used to specify what is published. For example, --project can be used to publish only a sub-project:

repo docs --stage publish --project my-sub-project

Likewise, --build can be used to publish a particular build:

repo docs --stage publish --build alternative-build

If you’re building documentation for multiple customers, each to their own website, it’s useful to define a customer specific edition and a customer specific build:

repo docs --stage publish --edition external-customer-website --build external-customer

The flags above can not only be combined, but also specified multiple times to publish multiple builds/projects/etc.

Publishing as the “latest” Version¶

Documentation is typically published to a directory that includes a version number (e.g. 106.0/). An index.html redirect can be created at that same level to point to the documentation that is being published. If the project has version selector feature enabled the version being published can be identified as the latest version. This is achieved by passing the --publish-as-latest flag during publishing:

repo docs --stage publish --edition s3web --publish-as-latest

This allows users to go to the folder that contains all of the versions of the documentation and be automatically redirected by their web browser to the “latest” version.

Example: Publishing to S3 via GitLab CI¶

GitLab’s .gitlab-ci.yml file can be updated to run the publish command as follows:

# the eks-docker tag tells gitlab to run on "runners" owned by omniverse
image: ubuntu:16.04

# this runs before each job's 'script'
before_script:
  - apt update
  - apt install -y curl

variables:
  AWS_ACCESS_KEY_ID: $AWS_OMNIVERSEDOCS_ACCESS_KEY_ID
  AWS_SECRET_ACCESS_KEY: $AWS_OMNIVERSEDOCS_SECRET_ACCESS_KEY

# this job only runs for MRs.  if the job is for MR !101, the docs are published to
# the mr101/ directory.
build-mr:
  tags:
    - eks-docker
  script:
    - ./repo docs
    - ./repo docs --stage publish --edition s3web
  only:
    # merge_requests is a gitlab keyword to denote the job is running for a MR
    - merge_requests

# this job runs only on the "main" branch. if there version of the code is 0.1.0,
# the docs will be published to the 0.1.0/ directory.
#
build-main:
  tags:
    - eks-docker
  script:
    - ./repo docs
    - ./repo docs --stage publish --edition s3web --publish-as-latest
  only:
    # this tells the job to only run on 'main'. your project may use the 'master'.
    - main

The script above, in combination with the repo.toml above, publishes to http://omniverse-docs.s3-website-us-east-1.amazonaws.com/repo_docs/.

Note

The AWS credentials used above are available in any repo under the Omniverse group.

Example: Publishing to GitLab Pages¶

GitLab supports serving static HTML. This HTML can be generated and deployed via .gitlab-ci.yml as follows:

# the eks-docker tag tells gitlab to run on "runners" owned by omniverse
image: ubuntu:16.04

# this runs before each job's 'script'
before_script:
  - apt update
  - apt install -y curl

# 'pages' is a special job in gitlab which publishes artifacts to a public website
#
# anything written to "public" will be published
pages:
  tags:
    - eks-docker
  script:
    - ./repo docs
    - mkdir public
    - cp -ar _build/docs/repo_docs/latest/* public
  artifacts:
    paths:
      - public

In your repo, navigate to Settings -> Pages -> Access pages to discover the URL that GitLab is serving your documentation under.

Note that the example above works for repos created under the Omniverse group. You could also use the shared Pages runners that are available to all repos on gitlab-master.nvidia.com. Consult this guide for details.

Example: Publishing to S3 via TeamCity¶

First you must provide the AWS credentials to the job that will execute the publishing. If your job is somewhere under the Omniverse project in TeamCity you can simply go to Settings -> Parameters -> Environment variables and make sure you have the following set:

Variable	Value
env.AWS_ACCESS_KEY_ID	%omniverse-docs.AWS_ACCESS_KEY_ID%
env.AWS_SECRET_ACCESS_KEY	%omniverse-docs.AWS_SECRET_ACCESS_KEY%
env.BUILD_BRANCH	%teamcity.build.branch%

Then have the job call a script that looks a lot like this:

#!/usr/bin/env bash

set -eu
set -o pipefail

SCRIPT_DIR="$(dirname "${BASH_SOURCE}")"
ROOT_DIR="$SCRIPT_DIR/../../../.."

# build docs
#
echo "##teamcity[blockOpened name='Building documentation']"
"$ROOT_DIR/repo" docs
echo "##teamcity[blockClosed name='Building documentation']"

# Publish the updated docs
echo "##teamcity[blockOpened name='Publishing documentation']"
if [ -z "$BUILD_BRANCH" ]; then
    return 1
fi

LATEST_ARG=""
if [ "$BUILD_BRANCH" == "refs/heads/master" ]; then
    LATEST_ARG=" --publish-as-latest"
fi

"$ROOT_DIR/repo" docs --stage publish --edition s3web $LATEST_ARG
echo "##teamcity[blockClosed name='Publishing documentation']"

That’s it! Your documentation will be found under http://omniverse-docs.s3-website-us-east-1.amazonaws.com/${bucket_dir} where bucket_dir is defined in your repo.toml (see section at top).