ACE documentation template

The ACE documentation template repository should be forked and used as a basis for all ACE-related microservice and workflow documentations. Doing so will ensure consistency across projects and it will also allow for the aggregation of different documentations in a central repository.

This repository uses the Omniverse repo tool suite. More specifically, it uses the repo_docs module to build the documentation and is based on a fork of the repo_minimal repository.

Build the documentation

Run .\build on Linux or .\build.bat on Windows to build the documentation.
Note: If you use VS Code and install the recommended arturodent.launch-config extension, you can also use the Ctrl+B shortcut to build the documentation.
Ensure that the documentation always builds without warnings or errors.
You can find the built HTML documentation in _build/docs/<project>/latest/index.html.

Edit the documentation

Recommended software setup

Even though there are multiple ways to edit markdown and reStructuredText, we recommend the following setup to get you up-to-speed quickly:

Download & install VS Code from https://code.visualstudio.com/.
Install the recommended extensions listed in .vscode/extensions.json with the VS Code extension manager after you checked out this repository.

Git setup

Download and install “Git for Windows” from https://gitforwindows.org/.
Create a new directory where you would like to check out this repository and navigate to it.
Run git clone https://gitlab-master.nvidia.com/omniverse/interactive-avatars/ace-documentation-template to check out the repository.

Contribute changes

Create a new branch named dev/your-feature or dev/your-username.
Make changes and push your branch.
Create a merge request here
Your submission will be reviewed and merged by documentation owner.

Add a video to the repository

Upload your video to the official YouTube NVIDIA channel. Most likely you will want to have an unlisted video. To request an upload, you can use the following form: Link
Once the video has been uploaded you can create a link to this external resource. We recommend embedding an image with a link to the YouTube video as shown in the example documentation.

Style guidelines

Titles should be capitalized like text This is how the title is formatted and not This Is How the Title Is Formatted.
If possible, all internal links should make use of anchors/ids to sections so that sections can be renamed without breaking links from other sections or workflow documentations.

Create a new documentation repository

Fork this repository
Enable LFS support on the repository if you plan to store a lot of images
Update the name, project, and other fields in the repo.toml file
Add a repository description and remove this section from this README.md file
Edit the index.rst and other reStructuredText or markdown files.

TODO

Find a way to use anchors in markdown links
Check how the embedding of the microservice documentation into main ACE documentation repo and linking from workflows to the microservice documentations works. Should we use a monorepo for the ACE documentation in combination with the only directive?
Figure out how to link from markdown to reStructuredText and vice versa? [My Label](/root-relative-url.html#anchor-in-page)?